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ABOUT THIS PUBLICATION 



VS APL is a program product that interprets and executes statements written 
in APL (A Programming Language). This publication describes how to install 
VS APL and how to perform various system management functions such as 
converting workspaces, defining VS APL users, and maintaining public and 
project libraries. It is intended for those who have responsibility for these 
functions. The reader is assumed to have knowledge of VS APL and 
Conversational Monitor System (CMS), which runs under VM/370, or 
Personal Computing (VSPC), which runs under OS/VS1 (Program Number 
5740-XR5), OS/VS2 (Program Number 5740-XR6), or DOS/VS (Program 
Number 5746-XR3). 

Unless noted otherwise, information in this publication about VS APL under 
VSPC applies to both OS/VS and DOS/VS. Information that pertains only to 
VS APL under DOS/VS (VSPC) will be provided for subsequent releases of 
VS APL. 

Major Divisions of the Publication 

"Introduction" describes the components of VS APL. 

"VS APL Distribution Volume" describes the contents and format of the VS 
APL distribution volume. 

"Installing VS APL under VM/370 (CMS)" explains how to install VS APL 
as a shared or non-shared system under VM/370 (CMS). 

"Installing VS APL under OS/VS (VSPC)" explains how to install VS APL 
as a foreground processor under OS/VS (VSPC). 

"Installing VS APL under DOS/VS (VSPC)" will, in a subsequent release, 
explain how to install VS APL as a foreground processor under DOS/VS 
(VSPC). 

"Defining VS APL Users" explains how to define VS APL users to the host 
system. 

"Defining Auxiliary Processors" explains how to define auxiliary processors 
to the host system. 

"VS APL Public and Project Libraries" explains how to create and maintain 
VS APL public and project libraries. 

"Workspace Conversion" explains how to convert APL\360, APLSV, and 
APL/CMS workspaces to VS APL workspaces for use under CMS or VSPC. 

"Transporting Workspaces between CMS and VSPC" explains how to 
transport VS APL workspaces between CMS and VSPC. 

"Using the VS APL Microcode Assist" discusses the use of the VS APL 
microcode assist feature. 

"Storage Requirements" presents virtual storage and auxiliary storage 
requirements for VS APL. 

"Messages" contains information about error and diagnostic messages. 

"Appendix A. VS APL Components" lists the items contained in each 
component of VS APL. 
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"Appendix B. Sample Terminal Session for VS APL under CMS" contains a 
sample terminal session that can be used to test that VS APL is installed 
correctly under CMS. 

"Appendix C. Sample Terminal Session for VS APL under VSPC" contains a 
sample terminal session that can be used to test that VS APL is installed 
correctly under OS/VS (VSPC) or DOS/VS (VSPC). 



Conventions Used in the Publication 



Required Publications 



The conventions used in describing the syntax of commands and statements 
are: 

• Expressions enclosed in brackets, [], are optional. 

• Items separated by an OR sign, | , are alternatives, only one of which may 
be specified. 

• Uppercase items must be entered as shown except that they may be 
truncated if so noted and, if entered at a terminal, they may be entered as 
either lowercase or uppercase. 

• Lowercase items are variables for which a value is substituted. 

• Parentheses, (), must be entered as shown. 



All readers must be familiar with some of the information presented in this 
publication: 

• VS APL General Information, GH20-9064, which provides a general 
description of VS APL. 

Readers concerned with VS APL under CMS must be familiar with some of 
the information presented in these publications: 

• IBM Virtual Machine Facility/ 370: Introduction, GC20- 1800, which 
provides a general description of VM/370 and CMS. 

• IBM Virtual Machine Facility/ 3 70: Command Language Guide for 
General Users, GC20-1804, which provides basic information about CMS 
and CP for VM/370 Release 2. 

• IBM Virtual Machine Facility/ 370: Operator's Guide, GC20-1806, 
which describes how to define VM/370 users and CMS virtual disks. 

• IBM Virtual Machine Facility/ 3 70: EDIT Guide, GC20- 1805, which 
describes how to use the CMS editor for VM/370 Release 2. 

• VS APL for CMS: Terminal User's Guide, SH20-9067, which 
describes how to use VS APL under CMS. 

• IBM Virtual Machine Facility/ 3 70: CMS User's Guide, GC20-1819, 
which provides basic information about CMS and how to use the CMS 
editor to create and modify programs for VM/370 Release 3. 

• IBM Virtual Machine Facility/ 3 70: CP Command Reference for 
General Users, GC20-1820, which provides basic information about CP 
for VM/370 Release 3. 
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Related Publications 



• IBM Virtual Machine Facility/ 3 70: Command and Macro Reference, 
GC20-1818, which provides reference material on CMS commands, 
subcommands, and macros for VM/370 Release 3. 

Readers concerned with VS APL under VSPC must be familiar with some of 
the information presented in these publications: 

• VS Personal Computing (VSPC) for OS/VS and DOS/VS: General 
Information, GH20-9070, which provides a general description of VSPC. 

• VS Personal Computing (VSPC) Installation Reference Material, 
SH20-9072, which describes the VSPC Service Program and the VSPC 
commands used in this publication. 

• VS APL for VSPC: Terminal User's Guide, SH20-9066, which 
describes how to use VS APL under VSPC. 

Readers concerned with VS APL under OS/VS (VSPC) must be familiar 
with some of the information presented in this publication: 

• OS/VS JCL Reference, GC28-061 8, which describes the OS/VS JCL 
statements used in this publication. 

Readers concerned with VS APL under DOS/VS (VSPC) must be familiar 
with some of the information presented in this publication: 

• DOS/VS System Control Statements, GC33-5376, which describes the 
DOS/VS control statements used in this publication. 



Readers may need to be familiar with some of the information presented in 
these publications: 

• Operator's Library: System/370 Model 135 Procedures, GC38-0005, 
which explains how to load the VS APL microcode assist feature on a 
System/370, Model 135. 

• IBM System/ 3 70 Model 145 Operating Procedures, GC3 8-00 15, which 
explains how to load the VS APL microcode assist feature on a 
System/370, Model 145. 

• IBM Virtual Machine Facility/ 370: System Messages, GC20-1808, 
which lists CP and CMS messages. 

• OS/VS Message Library: VSPC Messages for VS1, GC38-1013, 
which lists OS/VS (VSPC) messages. 

• DOS/VS Messages, GC33-5379, which lists DOS/VS (VSPC) messages. 

• IBM Virtual Machine Facility/ 370: System Programmer's Guide, 
GC20-1807, which describes shared systems. 

• IBM Virtual Machine Facility/ 370: Planning and System Generation 
Guide, GC20-1801, which describes how to implement a shared system. 
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INTRODUCTION 



VS APL is a program product that interprets and executes statements written 
in APL (A Programming Language). It runs under: 

• Conversational Monitor System (CMS), which runs under VM/370 

• Personal Computing (VSPC), which runs under OS/VS1, OS/VS2, and 
DOS/VS 

VS APL is divided into the six components described below. 

Interpreter: Scans, analyzes, and executes VS APL statements. It is fully 
independent of the environment in which VS APL operates. It is free of all 
dependencies on terminal type, library organization, host system, and other 
characteristics of a particular installation. 

Executor: Provides environment-dependent services for the interpreter, such 
as access to libraries and terminal input and output. There are two versions of 
the executor, one for use under CMS and one for use under VSPC. 

Shared Storage Manager: Enables programs that are operating concurrently 
to communicate with each other via shared variables. The shared storage 
manager distributed with VS APL is used only under CMS. Under VSPC, the 
shared storage manager is a component of VSPC. 

Auxiliary Processors: Provide services to VS APL users via shared variables. 
There are three internal auxiliary processors for use under VSPC; they are 
distributed as part of the executor. There are four auxiliary processors for use 
under CMS; they are distributed as a separate component. Also distributed 
with VS APL, for use under CMS only, is a set of macros that can be used to 
write auxiliary processors. Distributed with VSPC is a set of similar macros 
that comprise the VSPC background interface. 

Conversion Program: Converts APL\360, APLSV, and APL/ CMS 
workspaces to VS APL workspaces. There are four versions of the conversion 
program, two for use under CMS, one for use under OS/VS, and one for use 
under DOS/VS. 

Distributed Workspaces: Provide useful functions for VS APL users. They are 
described in VS APL for CMS: Terminal User's Guide and VS APL for 
VSPC: Terminal User's Guide. 
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VS APL DISTRIBUTION VOLUME 



The VS APL distribution volume contains all the components of VS APL and 
the sample job control statements and procedures used to install it. For 
installation under VM/370 (CMS) and OS/VS (VSPC), the distribution 
volume is tape. For installation under DOS/VS (VSPC), the distribution 
volume is either tape or disk. The format of the distribution volume is shown 
in Figure 1. 



File 

Number Contents 



File Characteristics 
RECFM LRECL BLKSIZE 



All object code for DOS/VS (VSPC); 
interpreter, executor (including internal 
auxiliary processors), and conversion 
program 1 . 

Sample job control statements to install 
under DOS/VS and to run the conversion 
program 1 . 

Sample job control statements to install 
under OS/VS and to run the conversion 
program. 

EXEC procedure to install under CMS; 
in CMS TAPE DUMP format. 

Object code for the interpreter for CMS 
and OS/VS (VSPC). 

Object code and other data for CMS; 
executor, shared storage manager, 
auxiliary processors, conversion programs, 
and conversion procedures; in CMS TAPE 
DUMP format. 

Object code for OS/VS (VSPC); executor 
(including internal auxiliary processors), 
and conversion program. 



FB 



FB 



FB 



80 



80 



80 



3440 



80 



80 



805 


805 


80 


3200 


805 


805 



80 



3200 



8 


Workspace 1 NEWS 


F 


800 


800 


9 


Workspace 1 WSFNS 


F 


800 


800 


10 


Workspace 1 CONVERT 


F 


800 


800 


11 


Workspace 1 TYPEDRILL 


F 


800 


800 


12 


Workspace 1 APLCOURSE 


F 


800 


800 


13 


Workspace 1 PLOT 


F 


800 


800 


14 


Workspace 1 EXAMPLES 


F 


800 


800 


15 


Workspace 1 FORMAT 


F 


800 


800 


16 


Workspace 2 VSFILES 2 


F 


800 


800 


17 


Workspace 2 APFNS3 


F 


800 


800 


18 


Macros to write auxiliary processors for CMS 


FB 


80 


3200 



1 Files 1 and 2 are dummy files. Their contents will be as described above for subsequent releases of VS APL. 

2 Workspace VSFILES is used only under VSPC. 

3 Workspace APFNS is used only under CMS. 

Figure 1. Format of VS APL Distribution Volume 
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INSTALLING VS APL UNDER VM/370 (CMS) 

This section describes how to install VS APL as a shared or non-shared 
system under VM/370 (CMS). Installing VS APL as a shared system makes 
more efficient use of real storage and improves system performance. When 
VS APL is a shared system, all users share one copy of the VS APL executor, 
interpreter, and shared storage manager; an initialization routine (executor 
module APLSCINI) resides in each user's virtual machine. When VS APL is a 
non-shared system, the VS APL executor, interpreter, and shared storage 
manager reside in each users' virtual machine. Whether VS APL is shared or 
not, any auxiliary processors invoked by a user reside in his virtual machine. 

Before installing VS APL as a shared system, you should be familiar with the 
information about saved systems and shared segments presented in IBM 
Virtual Machine Facility/ 3 70: System Programmer's Guide and IBM 
Virtual Machine Facility/ 370: Planning and System Generation Guide. 

Requirements for Installation 

The facilities required for installing VS APL under VM/370 (CMS) are: 

• A System/370 machine configuration that can support VM/370 (CMS). 

• An installed release of VM/370 (CMS) of the required level or later: 
Release 3 (Program Level Change 1) if installing VS APL as a shared 
system; Release 2 (Program Level Change 13) if installing VS APL as a 
non-shared system. PTF number V02960 must be applied to CMS if it is 
not included in the release. The CP macro SYSTIME, which is used to 
define the VM/370 system timer, should have a ZONE option that 
correctly specifies the offset from Greenwich Mean Time. Otherwise, the 
value of the UTS system variable and the time stamp printed in response 
to VS APL commands will be in Greenwich Mean Time. 

• A virtual machine large enough to install VS APL (see "Virtual Storage 
Requirements"). 

• A magnetic tape device. 

• The VS APL distribution tape. 

• A CMS A-disk large enough to contain the VS APL distributed files (see 
"Auxiliary Storage Requirements"). 

• A CMS Y-disk large enough to contain the generated VS APL system (see 
"Auxiliary Storage Requirements"). 

• If installing VS APL as a shared system, space on a CP-owned DASD 
volume for the system (see "Auxiliary Storage Requirements"). 

• A terminal supported by CMS. 
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Overview of Installation Procedure 



Installation Procedure 



In brief, the procedure for installing VS APL under VM/370 (CMS) is as 
follows. The procedure is described in detail in the next section. 

1. Plan and define the CMS disks required for VS APL. 

2. If installing VS APL as a shared system, plan the system's load address and 
DASD space allocation. 

3. Log on to VM/370 and IPL CMS. 

4. Access and prepare the A-disk and the Y-disk. 

5. Access the distribution tape. 

6. Transfer file APLINSTL EXEC (the CMS procedure that builds VS APL) 
from the distribution tape to the A-disk. 

7. Build VS APL by executing procedure APLINSTL. 

8. If installing VS APL as a shared system, define, load, and save the system. 

9. Test that VS APL is installed correctly by executing the sample terminal 
session (see Appendix B). 



1 . Plan the disk arrangement for the VS APL system, and define the disks as 
described in IBM Virtual Machine Facility/ 3 70: Operator's Guide. Two 
disks are required: 

• One which is accessed as the A-disk during execution of the installation 
procedure. It will contain all the files transferred from the distribution 
tape and the module files created in step 7. The minimum space required 
is shown in "Auxiliary Storage Requirements." Additional space should 
be allocated for future maintenance. At completion of the procedure, 
the A-disk should be kept as backup. 

• One which is accessed as the Y-disk during execution of the installation 
procedure. It will contain the generated VS APL system. The minimum 
space required is shown in "Auxiliary Storage Requirements." 
Additional space should be allocated for public workspaces other than 
those distributed. The Y-disk will be accessed by VS APL users. It 
should be defined with a write password known only to those who are 
responsible for installing and maintaining VS APL. 

2. If installing VS APL as a shared system, decide what the load address of 
the shared system will be. The address must be larger than the largest 
virtual machine of any VS APL user; the shared system must not overlay 
any other saved segment that will be attached at the same time as VS APL. 
The load address should not be unnecessarily high; if it is, real storage is 
wasted for unreferenced CP segment table entries. During step 7 of the 
installation procedure, enter the load address when prompted to do so. 

Also allocate permanent space on a CP-owned DASD volume to contain 
the saved system. For the space required, see "Auxiliary Storage 
Requirements." 

3. Log on to VM/370 and IPL CMS with a virtual machine large enough to 
install VS APL (see "Virtual Storage Requirements"). 
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4. Access the A-disk and the Y-disk in read/ write mode. If the disks are 
newly allocated, format them using the CMS FORMAT command. 

If the disks are not newly allocated, issue the CMS LISTFILE command, 
and check that no files with the identifications listed below exist. If there 
are any such files, rename them; otherwise they will be replaced in steps 6 
and 7. The files that are created on each disk are: 



Filename 


Filetype 


Disk 


APL 


EXEC 


AandY 


APL 


MODULE 


AandY 


APLCVCMS 


EXEC 


AandY 


APLCVCMS 


MODULE 


AandY 


APLCVRPQ 


EXEC 


AandY 


APLCVRPQ 


MODULE 


AandY 


APLIBTAB 


APLIBTAB 


AandY 


APLMAC 


MACLIB 


AandY 


APL100 


TEXT 


AandY 


APL101 


TEXT 


AandY 


APL110 


TEXT 


AandY 


APL111 


TEXT 


AandY 


APLMAIN 


MODULE 


Ai 


APL 


MAP 


A 


APLCVCMS 


MAP 


A 


APLCVRPQ 


MAP 


A 


Filename 


Filetype 


Disk 


macro-name 2 


MACRO 


A 


APLINSTL 


EXEC 


A 


module-name 3 


TEXT 


A 


APFNS 


W0000002 


Y 


APLCOURS 


W0000001 


Y 


CONVERT 


W0000001 


Y 


EXAMPLES 


W0000O01 


Y 


FORMAT 


W0000001 


Y 


NEWS 


W0000001 


Y 


PLOT 


W0000001 


Y 


TYPEDRIL 


W0000001 


Y 


WSFNS 


W0000001 


Y 



1 Created only when VS APL is installed as a shared system. 

2 There is a macro file for each macro listed in Appendix A under "Auxiliary Processor Macros." 

3 There is a text file for each module listed in Appendix A under "CMS Executor Modules," "Interpreter 
Modules," "Shared Storage Manager Modules," and "CMS Conversion Modules." 

5. Ask the system operator to mount the distribution tape and to attach the 
tape drive as virtual device 181, 182, 183, or 184. 

6. Transfer file APLINSTL EXEC (the CMS procedure that builds VS APL) 
from the distribution tape to the A-disk by issuing these CMS commands: 

TAPE REW (address 
TAPE FSF 3 ( address 
TAPE LOAD * * A (address 

address 

is the symbolic tape identification or the address of the device on which 
the distribution tape is mounted. 
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7. Invoke the procedure that builds VS APL by issuing this CMS command: 

APLINSTL 

The procedure is conversational; enter information when prompted to do 
so. The procedure performs the following actions: 

a. Transfers all required text and exec files (distribution tape files 5 and 6) 
from the distribution tape to the A-disk. 

b. Transfers the distributed workspace files from the distribution tape to 
the Y-disk (workspace VSFILES, which is used only under VSPC, is not 
transferred). 

c. Transfers the auxiliary processor macros from the distribution tape to 
the A-disk and generates file APLMAC MACLIB. 

d. Copies the following files from the A-disk to the Y-disk: 

• APL EXEC (VS APL startup procedure) 

• APLCVCMS EXEC (APL\360 and APLSV conversion program 
procedure) 

• APLCVRPQ EXEC (APL/CMS conversion program procedure) 

. APLIBTAB APLIBTAB (library table file) 

. APL100 TEXT, APL101 TEXT, APL1 10 TEXT, and APL1 1 1 
TEXT (auxiliary processors) 

• APLMAC MACLIB (auxiliary processor macro library) 

e. Creates files APL MODULE (initialization routine for shared system; 
executor, interpreter, and shared storage manager for non-shared 
system), APLMAIN MODULE (executor, interpreter, and shared 
storage manager for shared system), APLCVCMS MODULE 
(APL \ 3 60 and APLSV conversion program), and APLCVRPQ 
MODULE (APL/CMS conversion program). 

f . Copies files APL MODULE, APLCVCMS MODULE, and 
APLCVRPQ MODULE from the A-disk to the Y-disk. 

8. If installing VS APL as a shared system, define the system to CP and then 
load it and save it as follows: 

a. Define the system to be saved by adding a NAMESYS macro to your 
installation's DMKSNT ASSEMBLE module. Code the macro as 
follows: 

APLMAIN NAMESYS SYSNAME=APLMAIN, 
SYSSIZE=172K, 
VSYSADR=IGNORE, 
SYSVOL=ser ial-number , * 
SYSSTRT=( cylinder , page ) , 2 
SYSPGCT=48, 
SYSPGNM=( 128-175 ),3 
SYSHRSG=( 8,9, 10)3 

1 Provide the serial number of the volume on which space was allocated in step 2. 

2 Provide the starting cylinder and page address of the space allocated in step 2. 

3 The page and segment numbers shown are based on a load address of 512K. Provide the numbers 
that correspond to the load address you selected in step 2. 
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b. Assemble the new system name table (DMKSNT) by using the 
GENERATE EXEC procedure as described in IBM Virtual Machine 
Facility/ 3 70: Planning and System Generation Guide. 

c. Using a virtual machine large enough to contain the system to be saved 
(load address plus 400K), load the system and save it: 

LOADMOD APLMAIN 
SAVESYS APLMAIN 

d. Before continuing with step 9, log on to VM/370 with a smaller virtual 
machine (of a size no greater than the saved system's load address). 

9. Test that VS APL is installed correctly by executing the sample terminal 
session (see Appendix B). 

This completes the installation procedure. The A-disk should be kept for 
backup and maintenance of the system. The distributed workspaces must be 
kept on the Y-disk; that is, on the disk that is accessed as a Y-disk by VS 
APL users. The other files on the Y-disk (see list in step 4 above) can also be 
kept there or they can be transferred to the CMS system disk. 
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INSTALLING VS APL UNDER OS/VS (VSPC) 



This section describes how to install VS APL as a foreground processor under 
either OS/VS 1 (VSPC) or OS/VS2 (VSPC). 



Requirements for Installation 

The facilities required for installing VS APL under OS/VS are: 

A System/370 machine configuration that can support OS/VS 1 (VSPC) 
or OS/VS2 (VSPC). 

An installed release of OS/VS 1 (VSPC) or OS/VS2 (VSPC). 

OS/VS Linkage Editor; utility programs IEBPTPCH, IEHPROGM, and 
IEBUPDTE; and job control program IEFBR14. 

A region large enough to run the VSPC Service Program and the OS/VS 
Linkage Editor. 

A magnetic tape device. 

The VS APL distribution tape. 

Space in OS/VS1 SYS1.LINKLIB or OS/VS2 SYS1.LPALIB for the VS 
APL load module (see "Auxiliary Storage Requirements"). 

Space in OS/VS private libraries for the VS APL object decks and the 
conversion program load module (see "Auxiliary Storage Requirements"). 

Space in VSPC public libraries for the distributed workspaces (see 
"Auxiliary Storage Requirements"). 

Authorization to update OS/VS 1 SYS1.LINKLIB or OS/VS2 
SYS1.LPALIB. 

Authorization as a VSPC chief administrator. 

A terminal supported by VSPC (required only to execute the sample 
terminal session). 



Overview of Installation Procedure 



In brief, the procedure for installing VS APL under OS/VS (VSPC) is as 
follows. The procedure is described in detail in the next section. 

1 . Punch the sample JCL from the distribution tape. 

2. Allocate space for and catalog the data sets required for installing VS APL: 
VSAPL.OBJLIB and VSAPL.CNVTLIB. 

3. Transfer object modules from the distribution tape to data set 
VSAPL.OBJLIB. 

4. Link-edit the VS APL load module. 

5. Link-edit the conversion program into data set VSAPL.CNVTLIB. 
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Installation Procedure 



6. Run the VSPC Service Program to define VS APL, public libraries 1 and 2, 
and the internal auxiliary processors to VSPC and to transfer the 
distributed workspaces to the VSPC libraries. 

7. Test that VS APL is installed correctly by executing the sample terminal 
session (see Appendix C). 



1. Punch the OS/VS sample JCL procedures from the VS APL distribution 
tape by executing the following job: 

account ing-informat ion, MSGLEVEL=1 

PGM=IEBPTPCH 

SYSOUT=A 

DSN=JCL , VOL=SER=APLDTR , UNIT=2400 , 

DISP=OLD,LABEL=( 3,NL), 

DCB=( LRECL=80,BLKSIZE=80,RECFM=F ) 

SYSOUT=B 



There are six jobs in the sample JCL. The first five are used for each of the 
next five steps of the installation procedure. The last one is used to run the 
conversion program (see "OS/VS Workspace Conversion Program"). 

It may be necessary to alter the sample JCL to suit your requirements. In 
each step, the sample JCL is listed, and the modifications that may be 
required are noted. In this step and in steps 3 and 6, group name 2400 is 
used as the UNIT parameter to mean any magnetic tape device. In steps 4 
and 5, group name SYSDA is used as the UNIT parameter to mean any 
direct access device. If either of these names is not so defined for your 
installation, these parameters must be altered. 

2. Allocate space for two partitioned data sets and catalog them: 

• VSAPL.OBJLIB, object module library for the executor, interpreter, 
and conversion program. 

• VSAPL.CNVTLIB, load module library for the conversion program. 



//punchjc: 


L JOB 


// 


EXEC 


//SYSPRINT DD 


//SYSUT1 


DD 


// 




// 




//SYSUT2 


DD 


//SYSIN 


DD 


PUNCH 




/* 
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Execution of job ALLOC from the sample JCL, altered to suit your 
requirements, accomplishes this step. Supply the information shown in 
lowercase below. 

account ing-informat ion, MSGLEVEL=1 

PGM=IEFBR14 

DSN=VSAPL . OBJLIB , DISP= ( NEW , KEEP ) , 

VOL=SER=volser , UNIT=typeunit , 

SPACE=( 3520,(130,5,20)), 

DCB=(LRECL=80,BLKSIZE=3520,RECFM=FB) 

DSN=VSAPL . CNVTLIB , DISP=( NEW , KEEP ) , 

VOL=SER=volser , UNIT=typeunit , 

SPACE=(CYL,( 1,1,1)) 

PGM=IEHPROGM 

SYSOUT=A 

* 

VSAPL. OBJLIB, VOL=typeunit=volser 
VSAPL . CNVTLIB , VOL=typeunit=volser 
/* 

3. Transfer files 5 and 7 from the VS APL distribution tape to data set 
VSAPL.OBJLIB. Execution of job BUILDOBJ from the sample JCL, 
altered to suit your requirements, accomplishes this step. Supply the 
information shown in lowercase below. 

Each input file is a series of object modules, each preceded by a ./ ADD 
NAME= statement. The BUILDOBJ job reads the two files and writes 
each object module as a member of VSAPL.OBJLIB. 



//ALLOC 


JOB 


// 


EXEC 


//DD1 


DD 


// 




// 




// 




//DD2 


DD 


// 




// 




// 


EXEC 


//SYSPRINT DD 


//SYSIN 


DD 


CATLG 


DSNAME^ 


CATLG 


DSNAME= 


/* 





//BUILDOBJ JOB 

// EXEC 

//SYSPRINT DD 

//SYSUT2 DD 

//SYSIN DD 

// 

// 

// EXEC 

//SYSPRINT DD 

//SYSUT2 DD 

//SYSIN DD 

// 

// 

/* 



account ing- informat ion , MSGLEVEL= 1 

PGM=IEBUPDTE , PARM=NEW 

SYSOUT=A 

DSN=VSAPL . OBJLIB , DISP=OLD 

DSN=INTERP . OBJECT , VOL=SER=APLDTR , 

UNIT=2400 , DISP=( OLD , PASS ) , LABEL=( 5 , NL ) , 

DCB=(LRECL=80,BLKSIZE=3200,RECFM=FB) 

PGM=IEBUPDTE , PARM=NEW 

SYSOUT=A 

DSN=VSAPL . OBJLIB , DISP=OLD 

DSN=OSVS . DEPENDNT . OBJECT , VOL=SER=APLDTR , 

UNIT=2400 , DISP=OLD , LABEL=( 7 , NL ) , 

DCB=( LRECL=80 ,BLKSIZE=3200 ,RECFM=FB ) 
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//LINKAPL 


JOB 


// 


EXEC 


// 




//SYSPRINT 


DD 


//OBJLIB 


DD 


//SYSLMOD 


DD 


//SYSLMOD 


DD 


//SYSUT1 


DD 


//SYSLIN 


DD 



4. Link-edit the VS APL load module. Execution of job LINKAPL from the 
sample JCL, altered to suit your requirements, accomplishes this step. The 
job contains two SYSLMOD DD statements, one to link-edit VS APL into 
SYS1.LINKLIB for OS/VS1 and another to link-edit VS APL into 
SYS1.LPALIB for OS/VS2. Remove the statement that does not apply to 
your operating system, and supply the information shown in lowercase 
below. 

The link-edit map output from this step should be saved. 

account ing-informat ion, MSGLEVEL=1 

PGM=HEWL, 

PARM= ' RENT , NCAL , LIST , MAP , XREF ' 

SYSOUT=A 

DSN=VSAPL . OBJLIB , DISP=SHR 

DSN=SYS1 .LINKLIB,DISP=OLD (OS/VS1 ONLY) 

DSN=SYS1 .LPALIB,DISP=OLD ( OS/VS2 ONLY) 

UNIT=SYSDA,SPACE=(TRK,(40, 10 ) ) 

* 

INCLUDE OBJLIB( 1 ) 



ENTRY APLPCOEX 
SETCODE AC( 1 ) 
NAME APLPCOEX(R) 
/* 

* The sample JCL contains an INCLUDE statement for each module listed in Appendix A under "VSPC 
Executor Modules" and "Interpreter Modules." 

5. Link-edit the conversion program into data set VSAPL.CNVTLIB. 
Execution of job LINKCNVT from the sample JCL, altered to suit your 
requirements, accomplishes this step. Supply the information shown in 
lowercase below. 

The link-edit map output from this step should be saved. 

//LINKCNVT JOB account ing-informat ion, MSGLEVEL=1 
// EXEC PGM=HEWL , PARM= ' NCAL, LIST, MAP, XREF, REUS' 

//SYSPRINT DD SYSOUT=A 

//OBJLIB DD DSN=VSAPL. OBJLIB, DISP=SHR 
//SYSLMOD DD DSN=VSAPL. CNVTLIB,DISP=OLD 
//SYSUT1 DD UNIT=SYSDA,SPACE=(TRK,(40, 10 ) ) 
//SYSLIN DD * 
INCLUDE OBJLIB( * ) 



ENTRY CO IBM 
NAME APLCVOS(R) 
/* 

1 The sample JCL contains an INCLUDE statement for each module listed in Appendix A under 
"VSPC/OS Conversion Modules." 
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6. Run the VSPC Service Program to: 

• Define VS APL as a foreground processor. 

• Define public libraries 1 and 2. 

• Define the distributed auxiliary processors. 

• Transfer the distributed workspaces from the distribution tape to 
libraries 1 and 2 (workspace APFNS, which is used only under CMS, is 
not transferred). 

Execution of job VSPCSERV from the sample JCL, altered to suit your 
requirements, accomplishes this step. Supply the information shown in 
lowercase below. Although files 8 through 16 of the distribution tape 
contain 800-byte unblocked records, they must be described as 80-byte 
blocked records to the IMPORT function of the VSPC Service Program. 
See VSPC Installation Reference Material for a description of the VSPC 
Service Program and control statements. 

accounting-information, MSGLEVEL=1 
PGM=ASUSPEXC , PARM=NOLIST 
DSN=name , DISP=OLD 
DSN=name , DISP=OLD 
DSN=name , DISP=OLD 
DSN=NEWS , VOL=SER=APLDTR , 

UNIT=2400,DISP=( OLD, PASS ),LABEL=( 8,NL), 
DCB=( LRECL=80 , BLKSIZE=800 , RECFM=FBS ) 
DSN=WSFNS , VOL=SER=APLDTR , 
UNIT=2400 , DISP=( OLD , PASS ) , LABEL=( 9 , NL ) , 
DCB=(LRECL=80,BLKSIZE=800,RECFM=FBS) 
DSN=CONVERT , VOL=SER=APLDTR , 
UNIT=2400,DISP=( OLD, PASS ) ,LABEL=( 10, NL) , 
DCB=( LRECL=80 , BLKSIZE=800 , RECFM=FBS ) 
DSN=TYPEDRIL , VOL=SER=APLDTR , 
UNIT=2400,DISP=( OLD, PASS ),LABEL=( 1 1 ,NL), 
DCB=( LRECL=80 ,BLKSIZE=800 ,RECFM=FBS ) 
DSN=APLCOURS , VOL=SER=APLDTR , 
UNIT=2400,DISP=( OLD, PASS ),LABEL=( 12,NL), 
DCB=( LRECL=80 , BLKSIZE=800 , RECFM=FBS ) 
DSN=PLOT , VOL=SER=APLDTR , 

UNIT=2400,DISP=( OLD, PASS ),LABEL=( 13,NL), 
DCB=( LRECL=80 , BLKSIZE=800 , RECFM=FBS ) 
DSN=EXAMPLES , VOL=SER=APLDTR , 
UNIT=2400,DISP=( OLD, PASS ),LABEL=( 14, NL), 
DCB=( LRECL=80 , BLKSIZE=800 , RECFM=FBS ) 
DSN=FORMAT , VOL=SER=APLDTR , 
UNIT=2400 , DISP=( OLD , PASS ) , LABEL=( 1 5 , NL ) , 
DCB=( LRECL=80 , BLKSIZE=800 , RECFM=FBS ) 
DSN=VSFILES,VOL=SER=APLDTR, 
UNIT=2400 ,DISP=OLD , LABEL=( 1 6 ,NL ) , 
DCB=( LRECL=80 , BLKSIZE=800 , RECFM=FBS ) 
SYSOUT=A 



//VSPCSERV JOB 


// 


EXEC 


//SYSOLDIR DD 


//SYSOLIB1 


DD 


//SYSOLIB2 


DD 


//NEWS 


DD 


// 




// 




//WSFNS 


DD 


// 




// 




//CONVERT 


DD 


// 




// 




//TYPEDRIL DD 


// 




// 




//APLCOURS 


DD 


// 




//■ 




//PLOT 


DD 


// 




// 




//EXAMPLES 


DD 


// 




// 




//FORMAT 


DD 


// 




// 




//VSFILES 


DD 


// 




// 




//SYSPRINT 


DD 


//SYSIN 


DD 
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AUTH usernum/password 

DEFINE FP NAME(APL) CODE(AO) ENTRY! APLPCOEX ) 

DEFINE USER( 1 ) PAS SWD( password ) LIBTYPE( PUBLIC C)- 

SPACE(IOOO) PROJLIB(NONE) CONTENT! APL) INTPRMAX( 60 30) 
DEFINE USER(2) PAS SWD( password ) LIBTYPE( PUBLIC C)- 

SPACE(1000) PROJLIB(NONE) CONTENT(APL) INTPRMAX( 60 30) 
DEFINE AP(121) NOPASSWD SSMAX( 30 4000000) 
DEFINE AP(122) NOPASSWD SSMAX( 30 4058) 
DEFINE AP(123) NOPASSWD SSMAX( 30 32767) 
IMPORT 1 NEWS TYPE (OBJECT) CONTENT! APL) 
IMPORT 1 WSFNS TYPE ( OBJECT ) CONTENT(APL) 
IMPORT 1 CONVERT TYPE (OBJECT) CONTENT(APL) 
IMPORT 1 TYPEDRILL TYPE( OBJECT) CONTENT(APL) 
IMPORT 1 APLCOURSE TYPE (OBJECT) CONTENT(APL) 
IMPORT 1 PLOT TYPE( OBJECT) CONTENT ( APL ) 
IMPORT 1 EXAMPLES TYPE ( OBJECT ) CONTENT(APL) 
IMPORT 1 FORMAT TYPE ( OBJECT ) CONTENT (APL) 
IMPORT 2 VSFILES TYPE( OBJECT) CONTENT(APL) 
/* 

7. Test that VS APL is installed correctly by executing the sample terminal 
session (see Appendix C). 
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INSTALLING VS APL UNDER DOS/VS (VSPC) 



A description of how to install VS APL as a foreground processor under 
DOS/VS (VSPC) will be provided for subsequent releases of VS APL. 
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DEFINING VS APL USERS 

This section describes how to define VS APL users to VM/370 and VSPC. 

VM/370 User Directory 

Under CMS, a VS APL user is not defined as such. A VS APL user is a 
VM/370 user who has access to CMS and to VS APL and its libraries. The 
procedure for defining a VM/370 user directory entry is described in IBM 
Virtual Machine Facility/ 3 70: Operator's Guide. When defining a directory 
entry for a VS APL user, observe these guidelines: 

• The virtual machine must be large enough to execute VS APL (see 
"Virtual Storage Requirements"). If VS APL is installed as a shared 
system, the virtual machine size must be no larger than the load address of 
the shared system. 

• The user's CMS A-disk, in addition to whatever else he may use it for, is 
his VS APL private library. Define a disk at virtual device address 191 with 
sufficient space for anticipated workspace storage (see "Auxiliary Storage 
Requirements for Workspaces"). 

• The CMS Y-disk contains the VS APL public libraries; it can also contain 
other components of the VS APL system. Define a read-only link to this 
disk with virtual device address 19E. 

• Do not define a link to a disk that contains VS APL project libraries. VS 
APL links to a project library disk dynamically as a G-disk with virtual 
device address 197. Defining a link to a project library disk could prevent 
other VS APL users from accessing project libraries. Also, do not define a 
disk with virtual device address 197 for any VS APL user. 

• Define CMS as the system to be loaded when the user logs on. 



Defining VS APL Users 29 



V^fC User Prof Ue 



Under VSPC, a VS APL user is not necessarily defined as such. A VS APL 
user is a VSPC user whose profile includes the options required for using VS 
APL. Use the VSPC DEFINE command or the VSPC Service Program 
DEFINE control statement to define a new user's profile. Use the VSPC 
ALTER command or the VSPC Service Program ALTER control statement 
to modify an existing user's profile. They are described fully in VSPC 
Installation Reference Material. An example of DEFINE operands for a VS 
APL user is: 



Operand 

USER( 123456) 
PASSWD(MYPASS) 
LIBTYPE( PRIVATE) 
SPACE( 500 ) 

PROJLIB(512 ) 
CONTENT! APL) 



INTPRMAX( 100 50 



SSMAX(1000 5) 



Description 

Defines user number and library number 123456. 

Defines logon password. 

User's library is private. 

Maximum library space is 500 units (500,000 
bytes). 

User can access project library 512. 

When user logs on, he is under control of VS APL. 
If a CONTENT attribute other than APL is 
defined, the user can access VS APL by issuing the 
ENTER command. 

Maximum workspace size is 100 units (100,000 
bytes). Default workspace size is 50 units (50,000 
bytes). 

Maximum size of a single shared variable is 1000 
bytes. Maximum number of shared variables is 5. 



If the user intends to access VS APL workspaces in public or project libraries, 
the maximum workspace size must be at least as large as the maximum 
workspace size of those libraries. 

See also "Transferring Conversion Program Output to VSPC" for a 
discussion of how user profiles can be defined as a result of workspace 
conversion. 
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DEFINING AUXILIARY PROCESSORS 

This section describes how to define auxiliary processors to CMS and VSPC. 

Defining Auxiliary Processors to CMS 

Under CMS, auxiliary processors are not defined as such. An auxiliary 
processor exists as a CMS file whose filename is the name used to invoke it, 
whose filetype is TEXT, and whose filemode is any mode acceptable to CMS. 

Defining Auxiliary Processors to VSPC 

The internal auxiliary processors distributed with VS APL for use under 
VSPC are defined to VSPC during the installation procedure. They are 
identified as numbers 121 (APL VSPC file auxiliary processor), 122 
(EBCDIC VSPC file auxiliary processor), and 123 (VSAM file auxiliary 
processor). If you have obtained the source code for VS APL, you can change 
the numbers by performing these actions: 

1. Modify VS APL module APLPCOAP by specifying the new numbers as 
operands of the APAPL, APBCD, and APVSAM keywords of the 
APLPCOAP macro. Assemble the module. 

2. Link-edit the VS APL load module as described in the installation 
procedure. 

3. Execute the VSPC Service Program with DEFINE AP control statements 
to define the new numbers to VSPC (see VSPC Installation Reference 
Material). 

4. Specify the new numbers as the values of global variables APAP, APEP, 
and APVSAM in distributed workspace 2 VSFILES. 

To define a user- written auxiliary processor to VSPC, execute the VSPC 
Service Program with a DEFINE AP control statement as described in VSPC 
Installation Reference Material. 
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VS APL PUBLIC AND PROJECT LIBRARIES 



In this section, the procedures for creating and maintaining VS APL public 
and project libraries are described. 



VS APL Libraries under CMS 



Library Table File 



Under CMS, a VS APL public or project library is a collection of workspaces 
that has the properties described in the following sections. The libraries are 
defined in a CMS file called the library table file. When VS APL is installed, 
the library table file and public libraries 1 through 999 are created; no project 
libraries are created. 



The library table file defines public and project libraries to VS APL under 
CMS. The filename and filetype of the library table file are both APLIBTAB. 
The library table file distributed with VS APL defines libraries 1 through 999 
as public. When VS APL is installed, the file is placed on the Y-disk, but it 
can reside on any disk. It is located via the standard CMS search order. 

When VS APL is invoked, the library table file is read into virtual storage. 
When a VS APL user requests access to a public or project library, the 
executor searches the file sequentially from the beginning for the specified 
library number. The information from the first matching entry is used to 
identify the library type and, if a project library, to link dynamically to the 
project library disk. 

Records in the file are 80-byte card images of free format. Fields are 
delimited by one or more blanks. There are two types of records; each defines 
a single library or a range of libraries: 

PUBLIC libnuml ( f irst-libnum last-libnum) 

PROJECT libnuml ( f irst-libnum last-libnum) owner device 

PUBLIC or PROJECT 

is the library type; only the first two letters are required. 

libnum 

is a library number; it can be any positive integer other than 1001 
(reserved for VS APL users' private libraries) and no greater than seven 
digits. 

( f irst-libnum last-libnum) 

is a range of library numbers; the first number must be less than or equal to 
the second number. 

owner 

is the VM/370 user identification of the owner of the disk on which the 
project library resides. 

device 

is the virtual device address, as defined in the owner's directory entry, of 
the disk on which the project library resides. 

Use the CMS editor to maintain the library table file (see IBM Virtual 
Machine Facility/ 3 70: EDIT Guide). 
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Public Libraries 



How to Create a Public Library 



For VS APL under CMS, a public library is a collection of workspaces that 
has these properties: 

• It resides on a disk that is accessed as the Y-disk. The disk can contain 
more than one public library. It must not contain project libraries. 

• It is defined as a public library in the library table file. For example, public 
libraries 1 through 999 are defined as: 

PUBLIC ( 1 999 ) 

• Each workspace in the library is a CMS file whose filetype is Wnnnnnnn, 
where nnnnnnn is the library number. For example, workspace 1 NEWS is 
a CMS file whose filename is NEWS and whose filetype is W0000001. 

• Any VS APL user can list, load, or copy workspaces in the library. 

• No VS APL user can save or drop workspaces in the library. The library is 
maintained with CMS commands. 



Public libraries 1 through 999 are defined in the distributed VS APL system. 
The disk that contains public libraries is defined during the installation 
procedure. 

To create a public library with a number greater than 999 or to change the 
distributed definition of public libraries, use the CMS editor to modify the 
library table file. 



How to Maintain a Public Library 



Public library workspaces can be added, replaced, or deleted only by someone 
who is allowed write access to the public library disk. The maintenance 
functions are performed with CMS commands. The functions should be 
performed when no one is using VS APL. If this is not possible, notify VS 
APL users that they are not to access the Y-disk until the maintenance 
functions are completed. 

To add or replace a public library workspace: 

1. Have the VS APL user who created the workspace issue these CP and 
CMS commands to spool it to you: 

SPOOL PUNCH userid 

DISK DUMP filename filetype 

userid 

is your VM/370 user identification. 

filename filetype 

is the workspace identification. 

2. Access the public library disk in read/write mode and any filemode (B is 
used in the following examples). 

3. Transfer the workspace from the virtual reader to the A-disk: 

DISK LOAD 
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Project Libraries 



How to Create a Project Library 



4. Copy the workspace from the A-disk to the public library disk and rename 
it. Note that the filetype of private workspaces is VSAPLWS. For example: 

COPYFILE NEWPUB VSAPLWS A = W0000003 B (REPLACE 

Specify the REPLACE option only if the workspace is intended to replace 
one with the same identification. 

To delete a public library workspace: 

1. Access the public library disk in read/ write mode and any filemode. 

2. Erase the workspace. For example: 

ERASE NEWPUB W0000003 B 



For VS APL under CMS, a project library is a collection of workspaces that 
has these properties: 

• It resides on a disk that can be linked to dynamically as a G-disk with 
virtual device address 197. The disk can contain more than one project 
library. It must not contain public libraries. 

• It is defined as a project library in the library table file. For example, 
project library 2000 which is owned by CMS user ABC 1234 and resides 
on his disk at virtual device address 196 is defined as: 

PROJECT 2000 ABC1234 196 

• Each workspace in the library is a CMS file whose filetype is 'Wnnnnnnn, 
where nnnnnnn is the library number. For example, workspace 2000 
PROJWORK is a CMS file whose filename is PROJWORK and whose 
filetype is W0002000. 

• Any VS APL user who knows the read password defined for the disk can 
list, load, or copy workspaces in the library. 

• Any VS APL user who knows the write password defined for the disk can 
save or drop workspaces in the library. 



To create a project library, first decide whether it is to reside on an existing 
disk or on a new disk. It must reside on a new disk if maximum access control 
is wanted. VS APL users' access to project libraries is controlled by 
passwords associated with a disk, not with a library. 

To define the project library, use the CMS editor to add a record to the 
library table file. If the library is to reside on a new disk, define the disk as 
described in the following paragraphs; otherwise, creation of the library is 
completed. 
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The procedure for defining a disk (that is, for defining or modifying a 
VM/370 user directory entry) is described in IBM Virtual Machine 
Facility/ 370: Operator's Guide. When defining a project library disk, 
observe these guidelines: 

• Define the disk in a VM/370 user directory entry that is used for no 
purpose other than to contain the definition of the project library disk(s). 
This is recommended because VS APL links to project disks dynamically 
and cannot do so if a permanent link exists. If the disk is defined in an 
active VM/370 user directory entry, that user must detach the disk each 
time he logs on. 

• Define passwords as required to impose the desired level of control. A VS 
APL user must specify the read password for LIB, LOAD, and COPY 
commands; the write password for SAVE and DROP commands. To allow 
uncontrolled access, define a password as ALL. 

• Define sufficient space for anticipated workspace storage (see "Auxiliary 
Storage Requirements for Workspaces"). 

After the project library disk has been defined, format it using the CMS 
command FORMAT. 



How to Maintain a Project Library 



Project library workspaces can be added, replaced, or deleted by any user 
who knows the write password defined for the disk on which the project 
library resides. Maintenance is normally performed with VS APL commands 
SAVE and DROP; it can also be performed with CMS commands as 
described in "How to Maintain a Public Library." 



VS APL Libraries under VSPC 



Under VSPC, a VS APL public or project library is a VSPC public or project 
library that contains workspaces with a content attribute of APL. 

Use either the VSPC DEFINE command or the VSPC Service Program 
DEFINE control statement to create a public or project library (see VSPC 
Installation Reference Material). An example of DEFINE operands for a 
public library is: 

Operand Description 

USER( 3 ) Defines user number and library number 3. 

PASSWD( XYZ ) Defines password which must be specified to 

logon as user 3 or to gain access to the library; if 
access is not to be controlled, specify 
NOPASSWD. 

LIBTYPE( PUBLIC c ) Library is public; see discussion below of library 

maintenance for meaning of C. 

SPACE ( 1000) Maximum library space is 1000 units (1,000,000 

bytes). 

CONTENT ( APL ) Defines the content attribute of the workspace 

attached when a user logs on as user number 3. 

INTPRMAX( 100 50 ) Maximum workspace size is 100 units (100,000 

bytes); default workspace size is 50 units (50,000 
bytes). 
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The maximum workspace size must be no greater than that of VS APL users 
who access workspaces in the library. 

To define a project library, specify operands as above except for the library 
type, which is PROJECT rather than PUBLIC. 

Public and project libraries are maintained by users who have the requisite 
access to the libraries. In terms of library access, there are three types of 
users: 

• The library manager is the user who has logged on to VSPC by supplying 
the library number. 

• The workspace owner is the user who stored the workspace in the library. 

• Other users are those other than the library manager or workspace owner 
who are allowed to access the library. All users are allowed to access public 
libraries. Only those users whose profile definition includes the PROJLIB 
operand are allowed to access the specified project library. 

For both public and project libraries, if C is specified in the LIBTYPE 
operand when the library is defined, only the library manager can store, 
replace, or delete a workspace. If C is not specified, only the workspace 
owner can replace a workspace; either the workspace owner or the library 
manager can delete a workspace; other users can store new workspaces and 
thus become workspace owners. 

To store a new workspace or replace an existing one, use the VS APL 
command SAVE. To delete a workspace, use the VS APL command DROP 
or the VSPC command PURGE. 
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WORKSPACE CONVERSION 



General Information 



This section describes how to convert APIA 360, APLSV, and APL/CMS 
workspaces to VS APL workspaces. Throughout this section, the term source 
APL is used to mean APIA 360, APLSV, or APL/CMS. 



This section contains information that is applicable to workspace conversion 
under both CMS and VSPC unless noted otherwise. 



Pre-Conversion Considerations 



Conversion Input 



There are three items — library numbers, workspace names, and 
passwords — that may be unacceptable to CMS or VSPC. These items can be 
modified during the conversion procedure, as described later. However, they 
should be modified by the owners of the source APL workspaces before the 
workspaces are dumped. Modifying these items before rather than during the 
conversion procedure ensures that they are modified as the workspace owners 
wish them to be and simplifies the conversion procedure. 

The unacceptable items are: 

• A library number greater than seven digits. 

• A workspace name that contains deltas, underscored letters, lowercase 
letters, or national characters. 

• For CMS only, a workspace name longer than eight characters. 

• For VSPC only, a password that contains deltas or underscored characters. 
An invalid logon password can be altered by a VSPC administrator 
following conversion. An invalid workspace password must be modified by 
the workspace owner prior to conversion; a workspace with an invalid 
password cannot be accessed, and there is no way to alter the password. 



Input to the conversion procedure is a workspace dump tape from the source 
APL system. The tape can be multi-volume. For APL\360 and APLSV, the 
tape is produced by the source APL utility program; it can be a full dump, an 
incremental dump, or a selective dump. For APL/CMS, the tape is produced 
by the CMS TAPE DUMP command; it must contain only workspaces that 
were created on Version 2 of APL/CMS. 



Conversion Options 



There are three options that define which of the input workspaces are to be 

r»rrvr»e»cc*»rl • 



processed: 
Option 

Full 
Resume 

Select 



Description 

All workspaces on the input tape are processed. 

All workspaces on the input tape, beginning with a specified workspace, 
are processed. 

Only the specified workspaces are processed. 
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Conversion Output 



There are two options that define the type of conversion for the selected 
workspaces: 

Option Description 

Format Workspace is converted to the format defined for VS APL. 

Content Includes format conversion. In addition, all function statements are 

examined for items that will not execute correctly under VS APL. Such 
items are converted to their VS APL equivalent, if there is one. The 
incompatible items, whether converted or not, are reported. 

These types of conversion are described in greater detail in VS APL for 
CMS: Terminal User's Guide and VS APL for VSPC: Terminal User's 
Guide. 



Output of the conversion procedure is workspaces that can be executed by VS 
APL and a conversion report. The converted workspaces may or may not 
execute properly, depending on their content. The conversion report is 
intended for distribution to the owners of the workspaces. It gives 
information about the converted workspaces and, if content conversion was 
done, information about items that must be evaluated or modified by the 
workspace owner to ensure proper execution. 

Conversion program error messages are listed in the "Messages" section. 



Workspace Conversion under CMS 



There are two workspace conversion programs that execute under CMS: 
APLCVCMS converts APL \ 3 60 and APLSV workspaces for use under 
CMS; APLCVRPQ converts APL/ CMS workspaces for use under either 
CMS or VSPC. The procedures for using the two programs are described in 
this section and are the same unless noted otherwise. 



Auxiliary Storage Required by Conversion Programs 



When converting APL/CMS workspaces for use under VSPC, a scratch tape 
and A-disk space are required. The APLCVRPQ conversion program 
transfers each converted workspace to the tape and creates two files of job 
control statements on the converter's A-disk. The tape and the punched JCL 
files are subsequently used with the VSPC Service Program as described in 
step 6 of the conversion procedure, below. The amount of A-disk space 
required is n 800-byte blocks, where n is the number of converted 
workspaces multiplied by 0.3. 

When converting APL/CMS workspaces for use under CMS, APL \ 360 
workspaces, or APLSV workspaces, only A-disk space is required. The 
APLCVRPQ and APLCVCMS conversion programs transform each input 
workspace to a CMS file on the converter's A-disk. Estimate the amount of 
disk space required according to the number of workspaces to be converted, 
their size, and the amount of data they contain (see "Auxiliary Storage 
Requirements for Workspaces"). If possible, use an A-disk with sufficient 
space for all the workspaces to be converted. This should be possible if the 
input tape is a single volume. 
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The simplest way to convert a multi- volume input tape is to segment the job 
by volume. Allocate the maximum disk space allowed by CMS (246 
cylinders) and do a separate full conversion of each volume as if it were a 
complete dump tape. Directory information, which may be present on the first 
volume of the input tape, is not needed for VS APL under CMS and is 
ignored by the conversion program. 

See the last item in step 5 of the conversion procedure for a discussion of how 
to resume conversion if it terminates abnormally because of insufficient disk 
space. 



Identification of Converted Workspaces 



When an APL \ 360 or APLSV workspace is converted, its identification is 
transformed to a CMS file identification. The workspace name, truncated 
from the right to eight characters, becomes the CMS filename. The library 
number, truncated from the left to seven digits or extended to the left with 
zeros to seven digits, and prefixed with a W, becomes the CMS filetype. The 
CMS filemode is always Al. For example: 

Workspace Identification CMS File Identification 

25 GENWORK GENWORK W0000025 Al 

1234567 COMPUTATION COMPUTAT W1234567 Al 

12345678 XREF XREF W2345678 Al 

When an APL/ CMS workspace is converted, its identification (which is a 
CMS file identification) is retained with no change. The filetype of a private 
APL/CMS workspace is VMAPLWS. The filetype of a public APL/ CMS 
workspace is Pnnnnnn, where nnnnnn is the library number. 

After workspaces have been converted, it may be necessary to change their 
identification. This can be done as part of the conversion procedure (as 
described in step 6) or by the recipients of the converted workspaces. The 
required changes are: 

• The filetype of private workspaces must be changed to VSAPLWS. 

• For APL/CMS workspaces only, the filetype of public libraries must be 
changed to Wnnnnnnn, where nnnnnnn is the library number. 

• For APL/CMS workspaces only, lowercase letters or national characters 
that occur in a filename must be changed to uppercase letters or numbers. 



Workspace Conversion Procedure 



1. Log on to VM/370 and IPL CMS with a virtual machine large enough to 
execute the conversion program (see "Virtual Storage Requirements"). 

2. Access an A-disk in read/ write mode with the required amount of disk 
space (see "Auxiliary Storage Required by Conversion Programs"). If the 
disk is newly allocated, format it using the CMS FORMAT command. 

3. Ask the system operator to mount the workspace dump tape and to attach 
the tape drive as virtual device 181. If converting APL/CMS workspaces 
for use under VSPC, also ask the system operator to mount a scratch tape 
and to attach the tape drive as virtual device 182. 
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4. Invoke the conversion program and specify the desired options by issuing 
one of the following CMS commands: 

• To invoke the APIA 360 and APLSV conversion program: 

APLCVCMS [ FULL I RESUME I SELECT ] [ CONTENT I NOCONTENT ] 

The meaning of the operands is described in "Conversion Options"; 
NOCONTENT selects the format option. The operands can be 
truncated down to their initial character. The sequence in which the two 
operands are entered is immaterial. The default operands are FULL and 
CONTENT. 

• To invoke the APL/CMS conversion program: 

APLCVRPQ [FULL I RESUME] [CONTENT I NOCONTENT] 

The operands are as described above. Note that the SELECT option is 
not supported. 

5. The conversion procedure is conversational. Enter information as 
explained below when prompted to do so. If the information is an APL 
workspace identification, represent APL characters with EBCDIC 
characters as follows: 



APL 


EBCDIC 


0-9 


0-9 


A-Z 


a-z (lowercase) 


A-Z 


A-Z (uppercase) 


A 


* 


A 


$ 



Note that when the conversion program prints a workspace identification 
as part of a prompt, it uses A-Z to represent A-Z and a-z to represent 

a-z. 

• If the input option is RESUME, enter the identification of the 
workspace at which conversion is to begin as: 

library-number workspace-name 

• If the input option is SELECT, enter a list of the workspaces to be 
converted. The list can have up to 100 entries. Each entry can be one of 
the following: 

library- number workspace-name 
to select a specific workspace. 

1 ibrary- number 

to select all workspaces in a specific library. 

Press the RETURN key after each entry. Press the RETURN key alone 
to terminate the list. Entries in the list that are not found on the input 
tape are ignored. 

• If converting APL/CMS workspaces, enter YES or NO (depending on 
the destination of the converted workspaces) in response to this prompt: 

IS OUTPUT FOR VSPC (YES I NO) 
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• If a CMS file identification duplicates that of a file already on the 
A-disk, enter one of the following options: 

Option Description 

RENAME Give the workspace a new name. In response to the 

next two prompts for filename and filetype, enter the 
desired CMS filename and filetype or press the 
RETURN key alone to leave either one unchanged. 
Filetype, if entered, must be as described earlier (W 
followed by seven digits). 

IGNORE Reject the workspace; do not convert it. 

REPLACE Replace the existing CMS file with this one. 

CANCEL Terminate execution of the conversion program. 

• If a workspace name is invalid (contains deltas or underscored letters), 
enter the RENAME, IGNORE, or CANCEL option as described in the 
preceding step. 

• When end of volume is reached, either enter CANCEL to terminate 
execution of the conversion program, or do the following to continue 
with the next volume: 

- Enter CP mode by pressing the ATTN key twice. 

- Use the CP command MSG to ask the system operator to mount the 
next volume on the tape drive attached as virtual device 181. 

- Type the CP command BEGIN. 

- Type RESTART. 

• If the conversion program terminates abnormally because the A-disk is 
full or because of an unrecoverable error, the last partially converted 
workspace is erased from the A-disk and its identification is printed at 
the terminal. Process the workspaces that have been converted by doing 
step 6 of the conversion procedure. Then rewind the input tape by 
issuing this CMS command: 

TAPE REW 

and resume the conversion procedure at step 4. Specify the RESUME 
option and the identification of the workspace that was printed when 
the conversion program terminated. 

6. When the conversion program has completed execution, process the 
converted workspaces according to their destination: 

• If the converted workspaces are to be used with VS APL under CMS 
and are not owned by the converter, separate the conversion report into 
sections by library number and distribute the sections to their owners. 
Disperse the converted workspaces to their owners and erase them from 
the A-disk by doing one of the following: 

- To change the filetype of APL \ 360 or APLSV private workspaces to 
VSAPLWS before dispersing them, use the CMS editor to create a 
file named NEWTYPE EXEC containing these statements: 

SCONTROL ERROR 

RENAME 61 £2 &3 = VSAPLWS = 
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Then issue these CP and CMS commands for each owner: 

SPOOL PUNCH userid 

LISTFILE * filetype A (EXEC 

CMS NEWTYPE 

LISTFILE * VSAPLWS A (EXEC 

CMS DISK DUMP 

CMS ERASE 

userid 

is the owner's VM/370 user identification. 

filetype 

is that of the owner's workspaces in the form Wnnnnnnn; it can be 
obtained from the conversion report. 

- To disperse APIA 360 or APLSV workspaces without changing their 
filetype, issue these CP and CMS commands for each owner: 

SPOOL PUNCH userid 
LISTFILE * filetype A (EXEC 
CMS DISK DUMP 
CMS ERASE 

The operands are as described above. 

- To disperse APL/CMS workspaces, issue these CP and CMS 
commands for each workspace: 

SPOOL PUNCH userid 

DISK DUMP filename filetype 

ERASE filename filetype 

userid 

is the owner's VM/370 user identification. 

filename filetype 

is the identification of the APL/CMS workspace. 

If the converted workspaces are to be used with VS APL under CMS 
and are owned by the converter, the conversion procedure is completed 
except for changing the filetype. 

To change the filetype of all private workspaces, issue this CMS 
command: 

RENAME * filetype A = VSAPLWS = 

filetype 

is either that generated for APL \ 3 60 and APLSV workspaces in the 
form Wnnnnnnn, where nnnnnnn is the source APL library number; 
or VMAPLWS for APL/CMS workspaces. 

To change the filetype of APL/CMS public workspaces, issue this CMS 
command: 

RENAME * Pnnnnnn A = Wnnnnnnn = 

nnnnnn 

is the APL/CMS library number; note that the new filetype has an 
additional zero to the left. 
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If the converted workspaces are APL/CMS workspaces to be used 
under VSPC, use the output of the conversion program as input to the 
IMPORT function of the VSPC Service Program. 

There are two JCL files on the A-disk. The file named IMPORT 
DDCARDS contains the DD statement shown below for each converted 
workspace. The file named IMPORT COMMANDS contains the 
IMPORT statement shown below for each converted workspace. 

//ddname DD DSN=wsname,UNIT=2400 ,LABEL=( n,NL) , 

// VOL=SER=XXXX,DISP=( OLD, PASS ), 

// DCB=( LRECL=80 , BLKSIZE=800 , RECFM=FBS ) 

IMPORT wsname FROM ( ddname ) TYPE( OBJECT) CONTENT(APL) 

ddname 

is M1 through Mn, where n is the number of converted workspaces. 

wsname 

is the workspace name (the CMS filename). 

n 

is the position of the workspace on the output tape. 

The JCL files must be modified before they are used to run the VSPC 
Service Program. Use the CMS editor to modify them before printing 
and punching them, or modify them manually afterward. The required 
modifications are: 

- Add the JCL statements required by the service program. 

- Add an AUTH control statement. 

- In each DD statement, change XXXX to the serial number of the 
output tape. 

- If the output tape has standard labels, change the LABEL 
subparameter NL in each DD statement to SL. 

- If lowercase letters or national characters occur in a workspace name, 
change them to uppercase letters or numbers in the DD and IMPORT 
statements. 

- If the workspaces are to be transferred to VSPC libraries other than 
that specified in the AUTH control statement, insert the library 
number in each IMPORT statement preceding wsname. 

- If the VSPC host system is DOS/VS, use the information in file 
IMPORT DDCARDS to prepare the required TLBL statements. 

Print and punch the files by issuing these CMS commands: 

PRINT IMPORT DDCARDS 

PRINT IMPORT COMMANDS 

PUNCH IMPORT DDCARDS 

PUNCH IMPORT COMMANDS 

Send the output tape, the conversion report, and the printed and 
punched JCL files to the VSPC installation. 

At the VSPC installation, execute the VSPC Service Program to transfer 
the converted workspaces to VSPC libraries. IMPORT, AUTH, and the 
VSPC Service Program are described in VSPC Installation Reference 
Material. 
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Workspace Conversion under VSPC 



There is one workspace conversion program that executes under OS/VS 
(APLCVOS) and another that executes under DOS/VS (APLCVDOS). Both 
programs convert APIA 3 60 and APLSV workspaces. The procedures for 
using the two programs are described in this section and are the same unless 
noted otherwise. The procedure for converting APL/CMS workspaces for use 
under VSPC is described in "Workspace Conversion under CMS." 

Converting workspaces to be used under VSPC is basically a three-step 
procedure: 

1 . Execute the conversion program. The output is a conversion report and a 
data set which contains the converted workspaces and user profiles. 

2. Separate the conversion report into sections by library number and 
distribute the sections to their owners. 

3. Execute the VSPC Service Program with COPY control statements to 
transfer the converted workspaces to VSPC libraries and (optionally) to 
define their owners to VSPC. Input to the VSPC Service Program is the 
data set output by the conversion program. 

If the source APL dump tape contains library numbers or workspace names 
that are unacceptable to VSPC, the procedure must be executed twice. First 
do a full conversion. The unacceptable workspaces are rejected by the 
conversion program but identified on the conversion report. Then do a 
selective conversion of the rejected workspaces using information provided by 
the workspace owners to rename them. 



Conversion Control Statements 



Input to the conversion program is an APL \ 3 60 or APLSV workspace dump 
tape and a set of control statements as described below. All control 
statements are optional. A statement can appear anywhere within columns 1 
to 71 of a card; columns 72 to 80 are ignored; continuation is not allowed. 
The operands shown in uppercase can be truncated down to their initial 
character. Operands can be separated by blanks or parentheses. If an operand 
is an APL workspace identification, represent APL characters with EBCDIC 
characters as follows: 



APL 


EBCDIC 


0-9 


0-9 


A-Z 


A-Z (uppercase) 


A-Z 


a-z (lowercase) 


A 


* 


A 


$ 



FORMAT Statement 



Use the FORMAT statement to select format conversion. Omit the statement 
to select content conversion. The syntax of the statement, which has no 
operands, is: 

FORMAT 
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SELECT Statement 



RESUME Statement 



DESCRIBE Statement 



Use the SELECT statement to identify the libraries and/or workspaces to be 
converted during a selective conversion, and (optionally) to provide new 
identifications for workspaces with invalid library numbers or names. The 
maximum number of SELECT statements allowed is 100. If SELECT 
statements are included, RESUME is not allowed. For full conversion, omit 
both SELECT and RESUME statements. 

The syntax of the statement is: 

SELECT libnum [newlibnum] [wsname [newwsname] ] 

libnum 

is the library number of the source APL workspace. 

newlibnum 

is the VSPC library number; if omitted, the library number is 1 ibnum. The 
number cannot exceed seven digits. 

wsname 

is the name of the source APL workspace; if omitted, all workspaces in the 
specified library are selected. 

newwsname 

is the name of the workspace in VSPC; if omitted, the name is wsname. 
The name cannot exceed 1 1 characters and cannot contain deltas or 
underscored letters. 



Use the RESUME statement to identify the workspace at which conversion is 
to resume. If RESUME is used, SELECT statements are not allowed. For full 
conversion, omit both RESUME and SELECT statements. 

The syntax of the statement is: 

RESUME libnum wsname 

libnum 

is the library number of the source APL workspace. 

wsname 

is the name of the source APL workspace. 



Use the DESCRIBE statement to supply library space and shared variable 
space values. Only one DESCRIBE statement is allowed. The values apply to 
all libraries processed by the conversion program. 

The syntax of the statement is: 

DESCRIBE [LSPACE n] [SHARE m] 

LSPACE n 

is the maximum size of a library; n is units of 1000 bytes. 

SHARE m 

is the maximum size of a shared variable; m is units of 1000 bytes. 
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The conversion program determines library space for each user as follows: 

• If the input tape contains directories, the LSPACE operand of the 
DESCRIBE statement is ignored. The conversion program computes 
LSPACE according to the user's source APL workspace size (WSSIZE) 
and quota (WSQUOTA) as follows: 

X-*-20U80r6144 + l.lx^ J SSIZff 

Greater of 20K and source WS size plus 10% plus 6144 for internal 
buffers 

J«-2048xlp0 2048T2047+X 
Rounded to nearest 2K 

VSPCSIZE+lpO 1000T999+Z 

Rounded to nearest 1000 and converted to units of 1000 

LSPACE+VSPCSIZE*WSQUOTA 
Multiplied by workspace quota 

• If the input tape has no directories, LSPACE is as specified in the 
DESCRIBE statement. There are no directories if the input tape is a 
selective dump, or if it is multi-volume and the first volume is not input to 
the conversion program. 

• If there is no DESCRIBE statement, or if LSPACE is not specified, 
LSPACE is 500 units. 

The conversion program specifies each user's maximum shared variable size 
to be either that specified in the DESCRIBE statement or 0. It is the specified 
SHARE value if the input tape contains directories, the user's directory 
indicates a shared variable quota other than 0, and a SHARE value is 
specified in the DESCRIBE statement. In all other cases, SHARE is 0. For 
APL\360, which does not support shared variables, the SHARE value 
resulting from conversion is always 0. 

Note that APLSV defines the number of shared variables that a user can 
have, but does not restrict the size of a shared variable. Therefore, if a 
SHARE value is not defined to the conversion program and not otherwise 
defined to VSPC, or if the SHARE value is inadequate, a user who migrates 
to VS APL from APLSV will not be able to execute functions that use shared 
variables. 
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OS/VS Workspace Conversion Program 



Execution of job CONVERT from the sample OS/VS JCL distributed with 
VS APL can be used to run the OS/VS conversion program. Alter the job to 
suit your requirements as noted below. 

REGION=value 1 

PGM=APLCVOS 

DSN=VSAPL . CNVTLIB , DISP=SHR 

DSN=dsname,VOL=( PRIVATE, ,SER=volser ) , 

UNIT=2400,DISP=OLD,LABEL=( 1 ,BLP) 2 

DSN=dsname , VOL=( PRIVATE , , SER=volser ) , 

UNIT=2400 , DISP=OLD , LABEL=( 2 , BLP )2 

DSN=dsname , VOL=( PRIVATE , , SER=volser ) , 

UNIT=2400 , DISP=OLD , LABEL=( 3 , BLP )2 

UNIT=SYSDA, SPACE=( 8004 ,(5,5), RLSE P 

DSN=APLOUT , VOL=SER=volser , UNIT=2400 , 

DISP=( NEW, KEEP , KEEP ) , LABEL=( , SL )* 

SYSOUT=A,DCB=BLKSIZE=121 

SYSOUT=A 

* 

control statements 5 . 



//CONVERT 


JOB 


// 


EXEC 


//STEPLIB 


DD 


//APLTLBL 


DD 


// 




//APLTDTA 


DD 


// 




//APLTEOV 


DD 


// 




//APLDIRE 


DD 


//APLOUT 


DD 


// 




//APLRPRT 


DD 


//SYSUDUMP 


DD 


//SYSIN 


DD 


Insert conversion 


/* 





1 For region size, see "Virtual Storage Requirements." Supply other JOB parameters according to your 
requirements. 

2 The APLTLBL, APLTDTA, and APLTEOV DD statements describe the source APL dump tape. The 
conversion program bypasses label processing. Supply the information shown in lowercase. 

3 The APLDIRE DD statement describes a temporary data set used by the conversion program for directory 
entries (information about each input account number). Each 8004-byte block has space for 400 entries. 
The space allocation in the sample JCL allows for conversion of 32,000 account numbers. Modify the space 
allocation, if necessary. 

4 The APLOUT DD statement describes the sequential data set created by the conversion program. It can be 
tape, as described in the sample JCL, or disk. Supply the information shown in lowercase. If output to disk 
is wanted, supply the appropriate information. 

5 Insert conversion control statements after the SYSIN DD statement. 



DOS/VS Workspace Conversion Program 



A description of the procedure for executing the DOS/VS conversion 
program will be provided for subsequent releases of VS APL. 



User Profiles Created by Conversion Program 



The data set created by the conversion program contains a user profile for 
each converted library as well as the converted workspaces. The contents of 
each user profile created by the conversion program are: 

Item Value 

USER Source APL library number or new library number specified 

in SELECT statement. 

PASSWD Source APL logon password if directories were processed by 

conversion program; otherwise NOPASSWD. 

LIBTYPE Public library if USER is less than 1000; users other than the 

library manager can store files in the library (C is not 
specified). Private library if USER is greater than or equal to 
1000. 
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Item Value 

SPACE Library space quota as determined by conversion program. 

See discussion of LSPACE in "DESCRIBE Statement." 

CONTENT APL 

SIZE edit-size (maximum size for editable data) is 0. 

obj-size (maximum size for object programs) is 0. 

INTPRMAX maximum (maximum interpreter workspace size) is: 

J«-2 48 Or 6144 + 1. lxWSSIZE 

Greater of 20K and source WS size plus 10% plus 
6144 for internal buffers 

X+X+819 2 
Plus 8K 

X«-2048xlp0 2048T2047+X 
Rounded to nearest 2K 

MAXIMUM+lf>0 1000T999+X 

Rounded to nearest 1000 and converted to units of 
1000 

default (default interpreter workspace size) is VSPCSIZE 
(see "DESCRIBE Statement"). 

SSMAX size (maximum size of a shared variable) is as determined by 

conversion program. See discussion of SHARE in 
"DESCRIBE Statement." 

number (maximum number of shared variables) is source 
APL shared variable quota if directories were processed by 
conversion program; otherwise 0. Always for converted 
APL \ 3 60 workspaces. 

PROJLIB None 

JECODE None 

NO ADM User not authorized to use VSPC administrator commands. 



Transferring Conversion Program Output to VSPC 



When a converted workspace is transferred to VSPC, it becomes a file in the 
VSPC library. Its library number is the source APL library number or the new 
library number specified in a SELECT statement. Its name is the source APL 
workspace name or the new workspace name specified in a SELECT 
statement. Its password is the source APL workspace password. 

Use the COPY control statement of the VSPC Service Program to transfer 
the conversion program output (converted workspaces and user profiles) to 
the VSPC library. Each user profile that does not exist in the VSPC library is 
inserted. If a user profile does exist in the library, the profile created by the 
conversion program is ignored. The converted workspaces are added to the 
newly defined or existing user libraries. 
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If the owner of converted workspaces is a new VSPC user and if the profile 
created by the conversion program is not satisfactory, either (1) use DEFINE 
to create a user profile before transferring the conversion program output; or 
(2) use ALTER to modify the user profile after transferring the conversion 
program output. 

COPY, DEFINE, ALTER, and the VSPC Service Program are described in 
VSPC Installation Reference Material. 
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TRANSPORTING WORKSPACES BETWEEN CMS 
AND VSPC 



When transporting VS APL workspaces between CMS and VSPC, no 
conversion is required. VS APL workspaces have the same format under all 
host systems. 



Transporting Workspaces from CMS to VSPC 

1. At the CMS installation: 



a. Ask the system operator to mount a scratch tape and to attach the tape 
drive as virtual device 181, 182, 183, or 184. 

b. Access the disk(s) from which the workspaces are to be transferred in 
read/only mode. 

c. Transfer the workspaces to tape by issuing these CMS commands for 
each workspace: 

FILEDEF DISK filename filetype filemode 
FILEDEF TAPE TAPn ( RECFM F LRECL 800 BLOCK 800 
MOVEFILE DISK TAPE 

filename filetype filemode 

is the CMS identification of the workspace. 

TAPn 

is the magnetic tape device where n can be 1, 2, 3, or 4 to represent 
device 181, 182, 183, or 184 respectively. 

d. When all workspaces have been transferred to tape, rewind and unload 
the tape: 

TAPE RUN TAPn 

2. At the VSPC installation, execute the VSPC Service Program with 
IMPORT control statements, using the tape as input, to transfer the 
workspaces to VSPC libraries. Each workspace on the tape is a separate 
data set; use one DD or TLBL statement and one IMPORT control 
statement for each. Although the input data sets contain 800-byte 
unblocked records, they must be described as 80-byte blocked records to 
the service program. For example, to transfer the third workspace on the 
tape into OS/VS (VSPC) library 512 and give it a name of THIRDWS, 
use these statements: 

//THIRDWS DD DSN=THIRDWS , VOL=SER=volser , UNIT=2400 , 

// DISP=(OLD,PASS),LABEL=(3,NL), 

// DCB=( LRECL=80 ,BLKSIZE=800 ,RECFM=FBS ) 

IMPORT 512 THIRDWS TYPE( OBJECT) CONTENT(APL) 

See VSPC Installation Reference Material for a description of the VSPC 
Service Program and the IMPORT control statement. 



Transporting Workspaces between CMS and VSPC 53 



Transporting Workspaces from VSPC to CMS 



1. At the VSPC installation, execute the VSPC Service Program with 
EXPORT control statements to transfer the workspaces to tape. Transfer 
each workspace as an unlabeled data set containing 800-byte unblocked 
records; use one DD or TLBL statement and one EXPORT control 
statement for each. For example, to transfer a workspace named 
THIRDWS from OS/VS (VSPC) library 512 as the third data set on the 
tape, use these statements: 

//THIRDWS DD DSN=THIRDWS , VOL=SER=volser , UNIT=2400 , 

// DISP=(NEW,PASS),LABEL=( 3,NL), 

// DCB=( LRECL=800 ,BLKSIZE=800 , RECFM=F ) 

EXPORT 512 THIRDWS 

See VSPC Installation Reference Material for a description of the VSPC 
Service Program and the EXPORT control statement. 

2. At the CMS installation: 

a. Ask the system operator to mount the tape and to attach the tape drive 
as virtual device 181, 182, 183, or 184. 

b. Access the disk(s) to which the workspaces are to be transferred in 
read/ write mode. 

c. Transfer the workspaces from tape to disk by issuing these CMS 
commands for each workspace: 

FILEDEF DISK filename filetype filemode 
FILEDEF TAPE TAPn ( RECFM F LRECL 800 BLOCK 800 
MOVEFILE TAPE DISK 

filename 

is the name of the workspace. 

filetype 

is VSAPLWS if the workspace is transferred to a private library; it is 
Wnnnnnnn if the workspace is transferred to a public or project 
library, where nnnnnnn is the library number. 

filemode 

is that of the disk to which the workspace is transferred. 

TAPn 

is the magnetic tape device where n can be 1, 2, 3, or 4 to represent 
device 181, 182, 183, or 184 respectively. 
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USING THE VS APL MICROCODE ASSIST 



The VS APL microcode assist, which is available for System/370 Models 135 
and 145, performs some of the functions of the VS APL interpreter. The 
procedure for loading the microcode assist is described in Operator's Library: 
System/ 3 70 Model 135 Procedures and IBM System/ 3 70 Model 145 
Operator Procedures. If the microcode assist is there when VS APL is 
invoked, it is detected and used. 
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STORAGE REQUIREMENTS 



Virtual Storage Requirements 



Figure 2 shows the minimum virtual machine size (VM/370) and region size 
(OS/VS) required to install and execute VS APL and to execute the 
workspace conversion programs. Virtual storage requirements for VS APL 
under DOS/VS (VSPC) will be provided for subsequent releases of VS APL. 

Host To Install To Execute To Execute 

System VSAPL VS APL Conversion Program 

VM/370 (CMS) 400K 400R1 200K + 3.1 x WS5 for APLCVCMS 

(APL non-shared) 

200K + 2.1 x WS 6 for APLCVRPQ 

VM/370 (CMS) SSA2 + 400K 320K.3 as above 

(APL shared) 

OS/VS (VSPC) 256K 175K 4 124K + 3.1 x WS* 

1 Assumes a minimum-size workspace (20K) and no auxiliary processors. To execute with all distributed 
auxiliary processors and 4K of shared memory, add 20K. For additional shared memory or larger 
workspace, increase virtual machine size correspondingly. Users who access a large number of disks and 
files may require additional storage for CMS control blocks. 

2 Where SSA is the shared system's load address. 

3 This is the minimum-size CMS virtual machine. It allows a 100K workspace. You can increase the size of 
the virtual machine as noted in 1 above, but must not exceed the load address of the shared system. In 
addition, 192K (3 segments) of shared main storage is required. 

* This is the virtual storage required for the VS APL interpreter and executor (including the internal 
auxiliary processors), rather than the region size. It does not include virtual storage required for VSPC, 
access methods, and workspaces. 

5 Where WS is the size of each source APL workspace. 

6 Where WS is the size of the largest source APL workspace; virtual machine size must be at least 264K. 
Figure 2. Virtual Storage Requirements for VS APL 



Auxiliary Storage Requirements 

In this section, direct access storage devices are identified as follows: 
2314: IBM 2314 Direct Access Storage Facility and IBM 2319 Disk Storage. 
3330: IBM 3330 Disk Storage and IBM 3333 Disk Storage and Control. 
3340: IBM 3340 Direct Access Storage Facility. 



Auxiliary Storage Requirements for VS APL 



Figure 3 shows the minimum auxiliary storage required to install VS APL 
as a non-shared system under CMS. Note the columns that indicate whether 
the storage requirement applies to the A-disk, the Y-disk, or both. The total 
cylinder requirements for each disk are computed using the total block 
requirements; they are not the sum of the cylinders required for each 
component. 

Figure 4 shows a summary of the minimum auxiliary storage required to 
install VS APL as a shared system under CMS. The detail is as shown in 
Figure 3, except that component APL MODULE requires 8 blocks and there 
is an additional component, APLMAIN MODULE, that requires 232 blocks 
on the A-disk. 
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Component 


Disk 
A Y 


800-byte 
Blocks 


2314 


Cylinders 
3330 3340 


TEXT files for executor, 
interpreter, shared storage 
manager 


X 




620 


5 


3 7 


TEXT files for conversion 
programs 


X 




220 


2 


1 3 


Link-edit maps 


X 




120 




1 2 


Macros 


X 




100 




1 2 


APLINSTL EXEC 


X 




50 




1 1 


APL MODULE 


X 


X 


240 


2 


1 3 


APLCVCMS MODULE 


X 


X 


75 






APLCVRPQ MODULE 


X 


X 


75 






APL EXEC 


X 


X 


2 






APLCVCMS EXEC 


X 


X 


2 






APLCVRPQ EXEC 


X 


X 


2 






Auxiliary processors 


X 


X 


40 






APLMAC MACLIB 


X 


X 


95 






Library table file 


X 


X 


1 






Distributed workspaces 




X 


300 


2 


2 4 


Total for A-disk 


X 




1642 


11 


7 18 


Total for Y-disk 




X 


832 


6 


4 9 



Figure 3. Auxiliary Storage Requirements for Non-Shared VS APL under CMS 



Units Required 


2314 


Cylinders 
3330 


3340 


1642 


11 


7 


18 


600 


4 


3 


7 


49 


2 


1 


3 



Storage Device Unit of Storage 

A-disk 800-byte block 

Y-disk 800-byte block 

CP volume 4K page 

Figure 4. Auxiliary Storage Requirements for Shared VS APL under CMS 

Figure 5 shows the minimum auxiliary storage required to install VS APL 
under OS/VS (VSPC). The VSPC library storage requirement is for the 
distributed workspaces. 

The amount of auxiliary storage required to install VS APL under DOS/VS 
(VSPC) will be provided for subsequent releases of VS APL. 



Auxiliary Storage Requirements for Workspaces 



The amount of auxiliary storage required for a workspace depends on the 
amount of data it contains, not on the size of the workspace. To compute the 
number of bytes required to store a workspace, subtract the space available, 
UWA, from the workspace size, ) WSSIZE. 

Under VSPC, a VS APL workspace is a VSPC file. VSPC files are stored in 
units of 1000 bytes. 

Under CMS, a VS APL workspace is a CMS file with a block size of 800 
bytes. Figure 6 shows the capacity per cylinder of the direct access storage 
devices supported by CMS in terms of 800-byte blocks and several data sizes. 
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Data Set 


Data Set Type 


Number of 

Directory 

Blocks 


Unit of 
Storage 


Units 
Required 


SYS1.LINKLIB 
(OS/VS1 only) 


partitioned 


1 


cylinder 1 


1 


SYS1.LPALIB 

(OS/VS2 only) 


partitioned 


1 


cylinder 1 


1 


VSAPL.OBJLIB 


partitioned 


20 


3520-byte 
block 


130 


VSAPL.ClSfVTLIB 


partitioned 


1 


cylinder 1 


1 


VSPC library 


VSAM 


— 


1000-byte 
unit 


250 



1 Storage requirements for load module data sets are for a 3330. 

Figure 5. Auxiliary Storage Requirements for VS APL under OS/VS (VSPC) 









15K 


25K 


50K 


Device 


Blocks 


Clear WS 


Data 


Data 


Data 


2314 


150 


25 


7.5 


4.5 


2.3 


3330 


266 


44.3 


13.3 


8.1 


4.1 


3340 


96 


16 


4.8 


2.9 


1.5 



Figure 6. Auxiliary Storage Capacity per Cylinder 
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MESSAGES 
Messages under CMS 



Messages under VSPC 



Error and diagnostic messages that are issued by the CMS executor of VS 
APL are printed at the user's terminal. They are identified by a message 
number prefix of APL. They are documented in VS APL for CMS: 
Terminal User's Guide. 

A VS APL user can also receive messages issued by CP or CMS. CP and 
CMS messages are identified by message number prefixes of DMK and DMS, 
respectively. They are documented in IBM Virtual Machine Facility/ 3 70: 
System Messages. 



The following error and diagnostic messages are issued by the VSPC executor 
of VS APL and are printed on the VSPC online log. The VS APL user 
receives the message SYSTEM ERROR nnn, where nnn is the online log 
message number. 

APLP001I PGM CHECK LOOP IN APL PROCESSOR. 

Explanation: During processing of a program check, a second program check 
occurred. 

System Action: Message APLP011I, which shows the PSW and general 
registers at the time of the second program check, is issued. A dump is taken, 
and execution is terminated. 

User Action: Report the problem to the system programmer. 

APLP002I PGM CHECK IN EXECUTOR. 

Explanation: A program check occurred in the VS APL executor. 

System Action: Message APLP01 II, which shows the PSW and general 
registers at the time of the program check, is issued. A dump is taken, and 
execution is terminated. 

User Action: Report the problem to the system programmer. 

APLP003I EXECUTOR SAVE AREA BLOCK FULL. 

Explanation: The executor is designed so that routine calls are nested to a 
maximum depth of five. An attempt to call a sixth-level routine was made, 
and there is no sixth save area. 

System Action: A dump is taken, and execution is terminated. 

User Action: Report the problem to the system programmer. 

APLP004I INVALID ASSIST CHECK CONDITION CODE. 

Explanation: During initialization, when a test was made for the presence of 
the VS APL microcode assist, an unexpected condition code was returned. 

System Action: Execution continues without use of the VS APL microcode 
assist. 

User Action: Report the problem to the system programmer. 
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APLP005I UNEXPECTED SYSTEM ERROR CODE RECEIVED. 
RET: xxx, REAS: yyy, SYS: www, APL: zzzzz. 

Explanation: An unexpected error code was received from VSPC following a 
service request, xxx is the return code, yyy is the reason code, www is the 
VSPC request code, zzzzz is the VS APL service request code. 

System Action: A dump is taken. A clear workspace is loaded. Execution 
continues. 

User Action: Report the problem to the system programmer. 

APLP006I NO SYSTEM INDICATOR ON ASYNCH ENTRY. 

Explanation: VSPC invoked the VS APL processor for an asynchronous 
occurrence. No indicator was set to distinguish the cause. 

System Action: A dump is taken. Execution continues. 

User Action: Report the problem to the system programmer. 

APLP007I MULTIPLE UNEXPECTED ERROR CODES FROM 
SYSTEM. 

Explanation: Multiple unexpected error codes were received from VSPC 
following similar service requests. 

System Action: A dump is taken, and execution is terminated. 

User Action: Report the problem to the system programmer. 

APLP008I APL ASSIST INCOMPATIBLE WITH APL PROCESSOR. 

Explanation: During initialization, when a test was made for the presence of 
the VS APL microcode assist, it was discovered that the microcode assist is 
not at the same level as the VS APL processor. 

System Action: Execution continues without use of the VS APL microcode 
assist. 

User Action: Report the problem to the system programmer. 

APLP009I INSUFFICIENT STORAGE FOR MINIMUM WS. 

Explanation: The minimum workspace size defined in the user's profile is too 
small for VS APL operation. 

System Action: A dump is taken, and execution is terminated. 

User Action: Report the problem to the account administrator. 

APLPOllI PSW: xxxxxxxx xxxxxxxx, REGS: 

Explanation: VS APL has been terminated because of a program check. This 
message shows the contents of the program check old PSW and the general 
registers. It is issued following messages APLP001I or APLP002I. 

System Action: Abend processing continues. 

User Action: Include this information when reporting the problem to the 
system programmer. 
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APLP014I UNEXPECTED ERROR IN APL INTERNAL AP. 

Explanation: An unexpected error code was received from VSPC following a 
service request in an internal auxiliary processor. The prior message, 
APLP005I, gives additional information about the error. 

System Action: A dump is taken, and execution is terminated. 

User Action: Report the problem to the system programmer. 



Conversion Program Messages 



The following error messages are issued by workspace conversion programs 
and appear on the conversion report. With the conversion programs that run 
under CMS, the messages are also printed at the terminal. When a workspace 
or library is in error, its identification either appears in the message or 
preceding the message in the conversion report. 

There are messages in addition to those listed below that appear on the 
conversion report. They are directed to the workspace owner and are 
documented in VS APL for CMS: Terminal User's Guide and VS APL 
for VSPC: Terminal User's Guide. 

*** HDR LABEL I/O ERROR. CONVERSION CANCELLED 

Explanation: An unrecoverable error occurred while an input header label 
was being read. 

System Action: Execution of the conversion program is terminated. 

User Action: Obtain another copy of the input tape from the source APL 
system. 

Issued by: APLCVCMS, APLCVOS, APLCVDOS. 

*** TRLR LABEL I/O ERROR. CONVERSION CANCELLED 

Explanation: An unrecoverable error occurred While an input trailer label was 
being read. 

System Action: Execution of the conversion program is terminated. 

User Action: If the error occurred on the last or only volume, none. 
Otherwise, run the conversion program again using the remaining volumes. 

Issued by: APLCVCMS, APLCVOS, APLCVDOS. 

SYSTEM ERROR WHILE CONVERTING WORKSPACE/DIRECTORY 
libnum name. WORKSPACE/DIRECTORY UNCONVERTED AND 
PRESUMED DAMAGED 

Explanation: A program check occurred, probably because of invalid 
information in a workspace or directory. 

System Action: The contents of the program check old PSW and general 
registers are printed. Execution of the conversion program continues with the 
next workspace. 

User Action: Obtain another copy of the rejected workspace or library from 
the source APL system. 

Issued by: APLCVCMS, APLCVRPQ, APLCVOS, APLCVDOS. 
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ERROR UNRECOVERABLE. CONVERSION ABORTED 

Explanation: Repeated system errors have occurred. 

System Action: A storage dump is printed. Execution of the conversion 
program is terminated. 

User Action: Obtain another copy of the input tape from the source APL 
system. 

Issued by: APLCVCMS, APLCVRPQ, APLCVOS, APLCVDOS. 

*** WORKSPACE REJECTED, NOT CONVERTED, DUE TO I/O ERROR 

Explanation: An unrecoverable error occurred while the workspace was being 
read. 

System Action: Execution of the conversion program continues with the next 
workspace. 

User Action: Obtain another copy of the rejected workspace from the source 
APL system. 

Issued by: APLCVCMS, APLCVRPQ, APLCVOS, APLCVDOS. 

WORKSPACE FULL 

Explanation: The workspace is too large to be converted. 

System Action: Execution of the conversion program continues with the next 
object in the workspace. 

User Action: Have the owner of the source workspace compress it or split it 
into two workspaces and obtain a dump of the modified workspace. 

Issued by: APLCVCMS, APLCVOS, APLCVDOS. 

WRITE ERROR nn WHILE SAVING libnum name. CONVERSION 
CANCELLED 

Explanation: An error return from the FSWRITE macro occurred, nn is the 
return code (see IBM Virtual Machine Facility/ 3 70: Command Language 
Guide for General Users.) The probable cause of the error is a full A-disk 
(return code 13). 

System Action: Execution of the conversion program is terminated. 

User Action: Determine the reason for the error and correct it. Then run the 
conversion program again, specifying the RESUME option and the 
identification of the rejected workspace. 

Issued by: APLCVCMS. 

filename filetype IMPORT FILE SEQUENCE NUMBER nnnn 

Explanation: Display of the file sequence number nnnn of the converted 
workspace filename filetype on the output tape. 

System Action: None. 

User Action: Use the information when preparing VSPC Service Program 
control statements. 

Issued by: APLCVRPQ. 
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NOT A CMS DUMP TAPE. CONVERSION CANCELLED 

Explanation: The input tape is not a CMS dump tape. 

System Action: Execution of the conversion program is terminated. 

User Action: Mount the correct tape. 

Issued by: APLCVRPQ. 

filename filetype filemode NOT AN APL/CMS (PRPQ) WORKSPACE. 

Explanation: The file is not an APL/CMS workspace. 

System Action: Execution of the conversion program continues with the next 
file. 

User Action: None, unless all files on the tape are so rejected. In this case, 
mount the correct tape. 

Issued by: APLCVRPQ. 

INADEQUATE SPACE TO RUN CONVERSION. CONVERSION 
CANCELLED 

Explanation: There is less than 64K of free virtual storage space available. 

System Action: Execution of the conversion program is terminated. 

User Action: Define a larger virtual machine. 

Issued by: APLCVRPQ. 

filename filetype WORKSPACE TOO LARGE FOR VIRTUAL MACHINE 
SIZE. RERUN WITH LARGER MACHINE. WSSIZE IS xxxx NEED 
ABOUT yyyy BYTES TO CONVERT. 

Explanation: The workspace is too large to be converted. 

System Action: Execution of the conversion program continues with the next 
workspace. 

User Action: Define a larger virtual machine and run the conversion program 
again. 

Issued by: APLCVRPQ. 

filename filetype WORKSPACE DAMAGED OR INVALID. NOT 
CONVERTED. 

Explanation: Either internal pointers in the workspace are invalid, or the 
workspace is not Version 2. 

System Action: Execution of the conversion program continues with the next 
workspace. 

User Action: Obtain a valid copy of the rejected workspace from the source 
APL system. 

Issued by: APLCVRPQ. 
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*** WSID INVALID FOR VSPC. WORKSPACE (OR LIBRARY) 
REJECTED 

Explanation: The workspace name contains deltas or underscored characters 
or the library number exceeds seven digits. 

System Action: Execution of the conversion program continues with the next 
workspace. 

User Action: Run the conversion program again, using a SELECT statement 
to provide a valid identification for the rejected workspace or library. 

Issued by: APLCVOS, APLCVDOS. 

* TfflS LIBRARY DEFINED WITH DEFAULTS DUE TO SYSTEM 
ERROR 

Explanation: An error occurred while the directory for the library was being 
read. 

System Action: A user profile record containing default values for SPACE 
and SSMAX is written (see "User Profiles Created by Conversion Program"). 
Execution of the conversion program continues. 

User Action: If defaults are acceptable, none. Otherwise, use the VSPC 
command ALTER to modify the user's profile. 

Issued by: APLCVOS, APLCVDOS. 

SELECTION LIST FULL. COMMAND IGNORED 

Explanation: More than 100 SELECT statements were input to the 
conversion program. 

System Action: The SELECT statements in excess of 100 are ignored. 

User Action: Run the conversion program with the rejected SELECT 
statements. 

Issued by: APLCVOS, APLCVDOS. 

INVALID SELECT PARAMETER. COMMAND IGNORED 

Explanation: The SELECT statement contains an invalid parameter. 

System Action: The invalid statement is ignored. 

User Action: Correct the SELECT statement and run the conversion 
program again. 

Issued by: APLCVOS, APLCVDOS. 

INVALID DESCRIBE COMMAND. CONVERSION CANCELLED 

Explanation: The DESCRIBE statement contains an invalid parameter. 

System Action: Execution of the conversion program is terminated. 

User Action: Correct the DESCRIBE statement and run the conversion 
program again. 

Issued by: APLCVOS, APLCVDOS. 



66 VS APL Installation Reference Material 



INVALID CONVERSION OPTIONS. CONVERSION CANCELLED 

Explanation: Either the RESUME statement contains an invalid parameter or 
a conversion control statement is unrecognizable. 

System Action: Execution of the conversion program is terminated. 

User Action: Correct the invalid statement and run the conversion program 
again. 

Issued by: APLCVOS, APLCVDOS. 
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APPENDIX A. VS APL COMPONENTS 



Listed below are the items that 
are contained in each component 
of VS APL. When you install VS 
APL, check the printed output of 
the installation procedure against 
these lists to verify that each 
component is complete. 

Interpreter Modules 

APLCOIBM 

APLIACHK 

APLIACIR 

APLIADEC 

APLIADOM 

APLIAENC 

APLIAFOR 

APLIAGFM 

APLIAGOU 

APLIAGRD 

APLIANAM 

APLIAPRD 

APLIAQFN 

APLIARED 

APLIAROT 

APLIASCN 

APLIASHF 

APLIASHV 

APLIASYV 

APLIATAK 

APLIATBC 

APLIATRN 

APLIATRS 

APLIATSP 

APLIECMX 

APLIEFCH 

APLIEFNM 

APLIEIDX 

APLIEMND 

APLIEPSI 

APLIEREV 

APLIERHO 

APLIESCA 

APLIESPA 

APLIETAK 

APLIEXAR 

APLIEXFR 

APLITCMC 

APLITCMD 

APLITCME 

APLITCMF 

APLITCMG 

APLITCMI 



APLITCML 

APLITCMS 

APLITCMT 

APLITCPI 

APLITCPO 

APLITERR 

APLITEX 

APLITFCH 

APLITFDC 

APLITFDE 

APLITFDN 

APLITFDO 

APLITFUN 

APLITHDR 

APLITIDS 

APLITIHI 

APLITINI 

APLITINP 

APLITLXS 

APLITMSG 

APLITNCV 

APLITPRL 

APLITSUB 

APLITUSG 

CMS Executor Modules 

APLSCDPY 

APLSCERR 

APLSCFXI 

APLSCINI 

APLSCLIB 

APLSCMSC 

APLSCMSG 

APLSCOPY 

APLSCSHV 

APLSCSVI 

APLSCTBL 

APLSCTYP 

VSPC Executor Modules 

APLPAPAB 

APLPAPCD 

APLPCOAP 

APLPCOEX 

APLPCTBL 

APLPFXIM 

APLPLIBS 

APLPMISC 

APLPSERR 

APLPSHVR 

APLPTYIO 



Shared Storage Manager Modules 
(CMS only) 

ASUSHACC 

ASUSHBPB 

ASUSHBVB 

ASUSHCPY 

ASUSHGET 

ASUSHOFR 

ASUSHPUT 

ASUSHQUE 

ASUSHREF 

ASUSHRET 

ASUSHSOF 

ASUSHSON 

ASUSHSPC 

ASUSHSRD 

ASUSHSUB 

Auxiliary Processors (CMS only) 

APL 100 
APL101 
APL110 
APL111 

Auxiliary Processor Macros 
(CMS only) 

APLZCODE 

ASUPCV 

ASUSCV 

ASUSHSVP 

ASVPACC 

ASVPCPY 

ASVPOFR 

ASVPQRY 

ASVPREF 

ASVPRET 

ASVPSOF 

ASVPSON 

ASVPSPC 

ASVPWAIT 

CMS Conversion Modules (for 
APLCVCMS) 

APLCCULL 

APLCDISP 

APLCFUNC 

APLCGRUP 

APLCIBNM 

APLCINIT 

APLCLEAR 
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APLCMISC 

APLCOIBM 

APLCPARM 

APLCRPRT 

APLCSAVE 

APLCSHIP 

APLCSPIE 

APLCTBCD 

APLCVARB 

APLCWKSP 

APLCWSFN 

APLIESPA 

APLIEREV 

APLITFDC 

APLITHDR 

APLITIDS 

APLITLXS 

APLITNCV 



APLODISP 

APLOFUNC 

APLOGRUP 

APLOIBNM 

APLOINIT 

APLOLEAR 

APLOMISC 

APLOPARM 

APLORPRT 

APLOSAVE 

APLOSHIP 

APLOSLST 

APLOSPIE 

APLOTBCD 

APLOTIDY 

APLOVARB 

APLOWKSP 

APLOWSFN 



CMS Conversion Modules (for 
APLCVRPQ) 

APLCOIBM 

APLCSHIP 

APLCSPIE 

APLCTBCD 

APLIESPA 

APLITFDC 

APLITHDR 

APLITIDS 

APLITLXS 

APLITNCV 

APLQDISP 

APLQFUNC 

APLQGRUP 

APLQIBNM 

APLQINIT 

APLQLEAR 

APLQMISC 

APLQPARM 

APLQRPRT 

APLQSAVE 

APLQVARB 

APLQWKSP 

VSPC/OS Conversion Modules 

APLCOIBM 

APLIESPA 

APLIEREV 

APLITFDC 

APLITHDR 

APLITIDS 

APLITLXS 

APLITNCV 

APLOCULL 

APLODIRE 
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APPENDIX B. SAMPLE TERMINAL SESSION FOR 
VS APL UNDER CMS 



Log on to VM/370, IPL CMS, and execute the VS APL session shown 
below. You must have access to the disk on which the VS APL system resides 
and to the Y-disk on which the distributed workspaces reside. 



APL APL100 



V S APL 



CLEAR 



WS 
100 



USVO »J' 



X+'L * WO 0001 7 ! 



NEWS 

TYPEDRIL 

APLCOURS 

CONVERT 

EXAMPLES 

PLOT 

FORMAT 

WSFNS 



SAVED 



J/0000001 71 

J/0000001 71 

J/0000001 71 

tfOOOOOOl 71 

J/0000001 71 

J/0000001 71 

J/0000001 71 

J/0000001 71 

)L0AD 

08: 50 

FINDTYPE 



1 EXAMPLES 

42 06/12/75 
171 



FINDTYPE 7 



)0FF HOLD 



Invoke VS APL and the 
auxiliary processor that 
issues CP and CMS commands 



Establish connection with 
auxiliary processor 
Issue CMS command to list 
workspaces in public library 1 



PC 



Load workspace 

Data type of argument is . . . 

character 

Data type of argument is . . . 

numeric 

Log off VS APL and return 

to CMS 
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APPENDIX C. SAMPLE TERMINAL SESSION FOR 
VS APL UNDER VSPC 



Log on to VSPC and execute the VS APL session shown below. If the user 
number that you log on with has a content attribute of APL, omit the first 
statement. 



ENTER 


APL 








Invoke VS APL 




V S A 


P 


L 






CLEAR 


WS 










SAVED 


)L0AD 
11:05: 


2 1 

17 


/SFILES 
07/29/75 


Load workspace 




»S» ACREATE 


' SAMPLE • 


Create VSPC APL file to 




AWRITE 
AWRITE 


3 
4 


4pi 
3px 


12 
12 


be accessed sequentially 
Open file and write record 1 
Write record 2 




AREAD 








Read record 1 


1 2 


3 4- 










5 6 


7 8 










9 10 


11 12 
AREAD 








Read record 2 


1 2 


3 










4 5 


6 










7 8 


9 










10 11 


12 
AREAD 








There is no record 3; 
file is closed 


pcaL + 


DROP 'SAMPLE 
)0FF HOLD 


i 


Purge the file 

Log off VS APL and return 

to VSPC 
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GLOSSARY 



The following terms are defined as they are used in this 
publication. If you do not find the term you are looking for, 
refer to the index or to the IBM Data Processing Glossary, 
GC20-1699. 

A-disk: In CMS, a user's primary disk; accessed in read/write 
mode when a CMS terminal session is begun. 

account administrator: A VSPC user who has limited authority 
to use the VSPC Service Program and to define and alter user 
profiles. 

auxiliary processor: A program that communicates with other 
programs via shared variables. 

chief administrator: A VSPC user who has full authority to use 
the VSPC Service Program and to define and alter user, 
foreground processor, and auxiliary processor profiles. 

content attribute: In VSPC, information associated with a 
workspace that identifies its foreground processor or 
indicates its contents. 

content conversion: A form of workspace conversion in which 
the contents of a workspace are analyzed and modified; 
includes format conversion. 

conversion program: The component of VS APL that converts 
APIA 360, APLSV, and APL/CMS workspaces to VS APL 
workspaces. 

executor: The component of VS APL that provides 
environment-dependent services for the interpreter. 

filemode: In CMS, the third field of a file identifier; identifies 
the virtual disk on which the file resides and the mode in 
which the disk can be accessed. 

filename: In CMS, the first field of a file identifier. 

filetype: In CMS, the second field of a file identifier; may 
implicitly define certain file characteristics. 

foreground processor: A processor, such as VS APL, that 
operates under the control of VSPC. 

format conversion: A form of workspace conversion in which 
only the format of a workspace is modified. 

full conversion: A form of workspace conversion in which all 
input workspaces are converted. 

internal auxiliary processor: An auxiliary processor that is part 
of the VS APL (VSPC) executor, rather than a separate 
program. 

interpreter: The component of VS APL that scans, analyzes, 
and executes VS APL statements. 

library manager: A VSPC user whose user number is that of a 
public or project library. 

library table file: A file that defines public and project 
libraries to VS APL under CMS. 

private library: A library that is normally available only to a 
single user. 

profile: A collection of information about a user, a 
foreground processor, or an auxiliary processor. 

project library: A library that is normally available to a set of 
users. 



public library: A library that is normally available to all users. 

selective conversion: A form of workspace conversion in 
which only specified input workspaces are converted. 

service program: In VSPC, a program that is used to manage 
the VSPC library and to define and alter profiles. 

shared storage manager: The component of VSPC or of VS 
APL under CMS that manages the communication between 
auxiliary processors. 

system disk: In CMS, the disk that contains the CMS nucleus 
and disk-resident command modules; accessed in read/only 
mode when a CMS terminal session is begun. 

workspace: An area of virtual storage assigned to a user for 
his exclusive use. Also, the contents of that area when stored 
as a file. 

Y-disk: In CMS, a disk that is an extension of the system disk. 
It contains VS APL modules, procedures, and public libraries. 
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